@aiot-nexus/plugin-sdk 2.0.2 → 2.1.1

package/templates/sqlite/src/main.ts.tmpl

@@ -1,3 +1,5 @@
+import * as fs from "fs";
+import * as path from "path";
 import Database = require("better-sqlite3");
 import type {
   NexusResult,
@@ -6,50 +8,178 @@ import type {
   PluginRendererOperationRequest
 } from "@aiot-nexus/plugin-sdk";
 
-interface SqliteRecord {
-  id: number;
-  title: string;
-  note: string;
-  createdAt: string;
+type DatabaseSource = "default" | "external";
+type SqliteAffinity = "integer" | "real" | "text" | "blob" | "numeric";
+type LocatorKind = "primaryKey" | "rowid";
+
+interface DatabaseInfo {
+  databaseName: string;
+  databasePath: string;
+  source: DatabaseSource;
+  databaseReady: true;
+  notice?: string;
+}
+
+interface TableListRow {
+  schema: string;
+  name: string;
+  type: string;
+  ncol: number | bigint;
+  wr: number | bigint;
+  strict: number | bigint;
+}
+
+interface TableXinfoRow {
+  cid: number | bigint;
+  name: string;
+  type: string;
+  notnull: number | bigint;
+  dflt_value: unknown;
+  pk: number | bigint;
+  hidden: number | bigint;
+}
+
+interface TableIndexListRow {
+  origin: string;
+}
+
+interface TableSummary {
+  name: string;
+  columnCount: number;
+  withoutRowid: boolean;
+  strict: boolean;
+}
+
+interface ColumnInfo {
+  name: string;
+  declaredType: string;
+  affinity: SqliteAffinity;
+  nullable: boolean;
+  defaultSql: string | null;
+  primaryKeyOrder: number;
+  generated: boolean;
+  hidden: boolean;
+  insertable: boolean;
+  requiredOnInsert: boolean;
+  autoIntegerPrimaryKey: boolean;
+}
+
+interface TableSchema {
+  summary: TableSummary;
+  columns: ColumnInfo[];
+  visibleColumns: ColumnInfo[];
+  writableColumns: ColumnInfo[];
+  locator?: LocatorSpec;
+}
+
+interface LocatorSpec {
+  kind: LocatorKind;
+  columns: string[];
+  rowidAlias?: "rowid" | "_rowid_" | "oid";
+}
+
+type WireValue =
+  | { kind: "null" }
+  | { kind: "integer"; value: string }
+  | { kind: "real"; value: number }
+  | { kind: "text"; value: string; length: number; truncated: boolean }
+  | { kind: "blob"; hex: string; byteLength: number; truncated: boolean };
+
+interface LocatorValue {
+  column: string;
+  value: WireValue;
+}
+
+interface RowLocator {
+  kind: LocatorKind;
+  values: LocatorValue[];
+}
+
+interface TableRow {
+  cells: Array<{ column: string; value: WireValue }>;
+  locator?: RowLocator;
+}
+
+interface ActiveDatabase {
+  connection: Database;
+  databasePath: string;
+  source: DatabaseSource;
+  created: boolean;
+}
+
+interface PersistedState {
+  schemaVersion: 1;
+  databasePath: string;
 }
 
-const databaseName = "plugin.db";
-const tableName = "plugin_records";
-let database: Database | undefined;
-let databasePath = "";
-let databaseCreated = false;
+interface MutationValue {
+  mode: "default" | "unchanged" | "null" | "value";
+  value?: string;
+}
+
+interface ParsedMutations {
+  columns: string[];
+  values: unknown[];
+}
+
+interface ConvertedInputValue {
+  value: unknown;
+  byteLength: number;
+}
+
+const defaultDatabaseName = "plugin.db";
+const stateFileName = "sqlite-browser-state.json";
+const defaultTableName = "plugin_records";
+const allowedPageSizes = new Set([25, 50, 100]);
+const maximumTextPreviewBytes = 16 * 1024;
+const maximumBlobPreviewBytes = 32;
+const maximumFieldBytes = 1024 * 1024;
+const maximumRequestBytes = 4 * 1024 * 1024;
+const maximumBlobInputCharacters = maximumFieldBytes * 2 + 4096;
+const maximumLocatorBytes = 16 * 1024;
+const maximumSqliteIntegerCharacters = 20;
+const projectedValuesPerColumn = 4;
+const minimumSqliteInteger = -(1n << 63n);
+const maximumSqliteInteger = (1n << 63n) - 1n;
+
+let activeDatabase: ActiveDatabase | undefined;
+let activationContext: PluginMainActivationContext | undefined;
+let defaultDatabasePath = "";
+let stateFilePath = "";
+let databaseNotice: string | undefined;
+let databaseSelectionPending = false;
 
 export async function activate(context: PluginMainActivationContext): Promise<void> {
-  const fs = require("fs") as typeof import("fs");
-  const path = require("path") as typeof import("path");
+  activationContext = context;
   fs.mkdirSync(context.host.pluginDataDirectory, { recursive: true });
-  databasePath = path.join(context.host.pluginDataDirectory, databaseName);
-  databaseCreated = !fs.existsSync(databasePath);
-  database = new Database(databasePath);
-  database.pragma("journal_mode = DELETE");
-  database.prepare(
-    "CREATE TABLE IF NOT EXISTS " + tableName + " ("+
-      "id INTEGER PRIMARY KEY AUTOINCREMENT, "+
-      "title TEXT NOT NULL, "+
-      "note TEXT NOT NULL DEFAULT '', "+
-      "created_at TEXT NOT NULL"+
-    ")"
-  ).run();
-
-  await register(context, "sqlite.getInfo", getInfo);
-  await register(context, "sqlite.listRecords", listRecords);
-  await register(context, "sqlite.insertRecord", insertRecord);
-  await register(context, "sqlite.updateRecord", updateRecord);
-  await register(context, "sqlite.deleteRecord", deleteRecord);
-  const logResult = await context.host.log("info", "__PLUGIN_ID__ database " + (databaseCreated ? "created" : "loaded") + ": " + databasePath);
+  defaultDatabasePath = path.join(context.host.pluginDataDirectory, defaultDatabaseName);
+  stateFilePath = path.join(context.host.pluginDataDirectory, stateFileName);
+  activeDatabase = openInitialDatabase();
+
+  await register(context, "sqlite.getDatabaseInfo", handled(getDatabaseInfo));
+  await register(context, "sqlite.chooseDatabase", handledAsync(chooseDatabase));
+  await register(context, "sqlite.useDefaultDatabase", handledAsync(useDefaultDatabase));
+  await register(context, "sqlite.listTables", handled(listTables));
+  await register(context, "sqlite.readTable", handled(readTable));
+  await register(context, "sqlite.insertRow", handled(insertRow));
+  await register(context, "sqlite.updateRow", handled(updateRow));
+  await register(context, "sqlite.deleteRow", handled(deleteRow));
+
+  const applicationName = await context.host.electron.app.getName();
+  const logResult = await context.host.log(
+    "info",
+    "__PLUGIN_ID__ database " + (activeDatabase.created ? "created" : "loaded") + " in " + applicationName + ": " + activeDatabase.databasePath
+  );
   if (!logResult.ok) {
     throw new Error(logResult.error.message);
   }
 }
 
 export function deactivate(): void {
-  database?.close();
-  database = undefined;
+  activeDatabase?.connection.close();
+  activeDatabase = undefined;
+  activationContext = undefined;
+  databaseSelectionPending = false;
 }
 
 async function register(context: PluginMainActivationContext, name: string, handler: PluginRendererOperationHandler): Promise<void> {
@@ -59,140 +189,920 @@ async function register(context: PluginMainActivationContext, name: string, hand
   }
 }
 
-function getInfo(): Record<string, unknown> {
-  const activeDatabase = requireDatabase();
-  const countRow = requireObject(activeDatabase.prepare("SELECT COUNT(*) AS count FROM " + tableName).get(), "count row");
-  const latestRow = requireObject(activeDatabase.prepare("SELECT MAX(created_at) AS latest FROM " + tableName).get(), "latest row");
+function handled<TResult>(
+  action: (request: PluginRendererOperationRequest) => TResult
+): PluginRendererOperationHandler {
+  return (request) => {
+    try {
+      return success(action(request));
+    } catch (error: unknown) {
+      return sqliteFailure(error);
+    }
+  };
+}
+
+function handledAsync<TResult>(
+  action: (request: PluginRendererOperationRequest) => Promise<TResult>
+): PluginRendererOperationHandler {
+  return async (request) => {
+    try {
+      return success(await action(request));
+    } catch (error: unknown) {
+      return sqliteFailure(error);
+    }
+  };
+}
+
+function openInitialDatabase(): ActiveDatabase {
+  const persistedPath = readPersistedDatabasePath();
+  if (persistedPath) {
+    try {
+      return openExternalDatabase(persistedPath);
+    } catch (error: unknown) {
+      databaseNotice = "The recent database could not be reopened. The plugin database is active instead: " + errorMessage(error);
+      clearPersistedState();
+    }
+  }
+  return openDefaultDatabase();
+}
+
+function openDefaultDatabase(): ActiveDatabase {
+  const created = !fs.existsSync(defaultDatabasePath);
+  const connection = new Database(defaultDatabasePath);
+  try {
+    connection.defaultSafeIntegers(true);
+    connection.pragma("journal_mode = DELETE");
+    connection.prepare(
+      "CREATE TABLE IF NOT EXISTS " + quoteIdentifier(defaultTableName) + " ("+
+        "id INTEGER PRIMARY KEY AUTOINCREMENT, "+
+        "title TEXT NOT NULL, "+
+        "note TEXT NOT NULL DEFAULT '', "+
+        "created_at TEXT NOT NULL DEFAULT (strftime('%Y-%m-%dT%H:%M:%fZ', 'now'))"+
+      ")"
+    ).run();
+    validateDatabase(connection);
+    return { connection, databasePath: defaultDatabasePath, source: "default", created };
+  } catch (error: unknown) {
+    connection.close();
+    throw error;
+  }
+}
+
+function openExternalDatabase(filePath: string): ActiveDatabase {
+  const normalizedPath = path.resolve(filePath);
+  const stat = fs.statSync(normalizedPath);
+  if (!stat.isFile()) {
+    throw new Error("The selected path is not a file.");
+  }
+  const connection = new Database(normalizedPath, { fileMustExist: true, readonly: false, timeout: 5000 });
+  try {
+    connection.defaultSafeIntegers(true);
+    validateDatabase(connection);
+    return { connection, databasePath: normalizedPath, source: "external", created: false };
+  } catch (error: unknown) {
+    connection.close();
+    throw error;
+  }
+}
+
+function validateDatabase(connection: Database): void {
+  connection.prepare("SELECT name FROM main.sqlite_schema ORDER BY name LIMIT 1").get();
+}
+
+function getDatabaseInfo(): DatabaseInfo {
+  const current = requireDatabase();
+  const notice = databaseNotice;
+  databaseNotice = undefined;
   return {
-    databaseName,
-    databasePath,
-    databaseCreated,
-    tableName,
-    recordCount: typeof countRow.count === "number" ? countRow.count : 0,
+    databaseName: path.basename(current.databasePath),
+    databasePath: current.databasePath,
+    source: current.source,
     databaseReady: true,
-    latestCreatedAt: typeof latestRow.latest === "string" ? latestRow.latest : null
+    ...(notice ? { notice } : {})
   };
 }
 
-function listRecords(): { records: SqliteRecord[] } {
-  const rows = requireDatabase().prepare(
-    "SELECT id, title, note, created_at AS createdAt FROM " + tableName + " ORDER BY id DESC LIMIT 100"
-  ).all();
-  return { records: rows.map(readRecordRow) };
+async function chooseDatabase(): Promise<{ canceled: boolean; database: DatabaseInfo }> {
+  if (databaseSelectionPending) {
+    throw codedError("Busy", "A database selection dialog is already open.");
+  }
+  const context = requireActivationContext();
+  databaseSelectionPending = true;
+  try {
+    const current = requireDatabase();
+    const result = await context.host.electron.dialog.showOpenDialog({
+      title: "Open SQLite database",
+      defaultPath: path.dirname(current.databasePath),
+      properties: ["openFile"],
+      filters: [
+        { name: "SQLite databases", extensions: ["db", "db3", "sqlite", "sqlite3"] },
+        { name: "All files", extensions: ["*"] }
+      ]
+    });
+    if (result.canceled || result.filePaths.length === 0) {
+      return { canceled: true, database: getDatabaseInfo() };
+    }
+    const candidate = openExternalDatabase(result.filePaths[0]);
+    try {
+      persistDatabasePath(candidate.databasePath);
+      replaceDatabase(candidate);
+      databaseNotice = undefined;
+    } catch (error: unknown) {
+      candidate.connection.close();
+      throw error;
+    }
+    await logDatabaseSwitch("external", path.basename(candidate.databasePath));
+    return { canceled: false, database: getDatabaseInfo() };
+  } finally {
+    databaseSelectionPending = false;
+  }
 }
 
-function insertRecord(request: PluginRendererOperationRequest): NexusResult<never> | { record: SqliteRecord } {
-  const inputResult = readRecordInput(request.input, "Insert");
-  if (!inputResult.ok) {
-    return inputResult;
+async function useDefaultDatabase(): Promise<{ database: DatabaseInfo }> {
+  const candidate = openDefaultDatabase();
+  try {
+    clearPersistedState();
+    replaceDatabase(candidate);
+    databaseNotice = undefined;
+  } catch (error: unknown) {
+    candidate.connection.close();
+    throw error;
   }
-  const createdAt = new Date().toISOString();
-  const activeDatabase = requireDatabase();
-  const insertResult = activeDatabase.prepare(
-    "INSERT INTO " + tableName + " (title, note, created_at) VALUES (?, ?, ?)"
-  ).run(inputResult.value.title, inputResult.value.note, createdAt);
-  const id = Number(insertResult.lastInsertRowid);
-  const record = readRecord(id);
-  if (!record) {
-    throw new Error("Inserted SQLite record could not be read.");
+  await logDatabaseSwitch("default", defaultDatabaseName);
+  return { database: getDatabaseInfo() };
+}
+
+async function logDatabaseSwitch(source: DatabaseSource, databaseName: string): Promise<void> {
+  const context = activationContext;
+  if (!context) {
+    return;
   }
-  return { record };
+  await context.host.log("info", "__PLUGIN_ID__ switched to " + source + " database: " + databaseName);
+}
+
+function replaceDatabase(candidate: ActiveDatabase): void {
+  const previous = activeDatabase;
+  activeDatabase = candidate;
+  previous?.connection.close();
+}
+
+function listTables(): { tables: TableSummary[] } {
+  return { tables: readTableSummaries(requireDatabase().connection) };
+}
+
+function readTable(request: PluginRendererOperationRequest): {
+  table: TableSummary;
+  columns: ColumnInfo[];
+  rows: TableRow[];
+  totalRows: string;
+  offset: number;
+  limit: number;
+  hasPrevious: boolean;
+  hasNext: boolean;
+  writable: boolean;
+  locatorKind?: LocatorKind;
+} {
+  const input = requireInput(request.input);
+  const tableName = readRequiredString(input.table, "table", 512);
+  const offset = readOffset(input.offset);
+  const limit = readPageSize(input.limit);
+  const connection = requireDatabase().connection;
+  const schema = readTableSchema(connection, tableName);
+  const totalRows = readCount(connection, schema.summary.name);
+  const selectList = [
+    ...locatorProjection(schema),
+    ...schema.visibleColumns.flatMap(previewProjection)
+  ].join(", ");
+  const orderBy = orderByClause(schema.locator);
+  const rawRows = requireArrayRows(
+    connection.prepare(
+      "SELECT " + selectList + " FROM " + quoteIdentifier(schema.summary.name) + orderBy + " LIMIT ? OFFSET ?"
+    ).raw(true).all(limit, offset)
+  );
+  const rows = rawRows.map((rawRow) => readTableRow(schema, rawRow));
+  return {
+    table: schema.summary,
+    columns: schema.columns,
+    rows,
+    totalRows: totalRows.toString(),
+    offset,
+    limit,
+    hasPrevious: offset > 0,
+    hasNext: BigInt(offset + rows.length) < totalRows,
+    writable: schema.writableColumns.length > 0,
+    ...(schema.locator ? { locatorKind: schema.locator.kind } : {})
+  };
 }
 
-function updateRecord(request: PluginRendererOperationRequest): NexusResult<never> | { record: SqliteRecord } {
-  const idResult = readRecordId(request.input, "Update");
-  if (!idResult.ok) {
-    return idResult;
+function insertRow(request: PluginRendererOperationRequest): { changes: number; lastInsertRowid: string | null } {
+  const input = requireInput(request.input);
+  const tableName = readRequiredString(input.table, "table", 512);
+  const schema = readTableSchema(requireDatabase().connection, tableName);
+  const parsed = parseMutations(schema, input.values, "insert");
+  const sql = parsed.columns.length === 0
+    ? "INSERT INTO " + quoteIdentifier(schema.summary.name) + " DEFAULT VALUES"
+    : "INSERT INTO " + quoteIdentifier(schema.summary.name)
+      + " (" + parsed.columns.map(quoteIdentifier).join(", ") + ")"
+      + " VALUES (" + parsed.columns.map(() => "?").join(", ") + ")";
+  const result = requireDatabase().connection.prepare(sql).run(...parsed.values);
+  return {
+    changes: result.changes,
+    lastInsertRowid: result.lastInsertRowid === undefined || result.lastInsertRowid === null
+      ? null
+      : String(result.lastInsertRowid)
+  };
+}
+
+function updateRow(request: PluginRendererOperationRequest): { changes: number } {
+  const input = requireInput(request.input);
+  const tableName = readRequiredString(input.table, "table", 512);
+  const connection = requireDatabase().connection;
+  const schema = readTableSchema(connection, tableName);
+  const locator = parseLocator(schema, input.locator);
+  const parsed = parseMutations(schema, input.values, "update");
+  if (parsed.columns.length === 0) {
+    throw codedError("InvalidRequest", "Update requires at least one changed column.");
   }
-  const inputResult = readRecordInput(request.input, "Update");
-  if (!inputResult.ok) {
-    return inputResult;
+  const where = buildLocatorWhere(schema, locator);
+  const sql =
+    "UPDATE " + quoteIdentifier(schema.summary.name)
+      + " SET " + parsed.columns.map((column) => quoteIdentifier(column) + " = ?").join(", ")
+      + " WHERE " + where.sql;
+  return { changes: runSingleRowMutation(connection, sql, [...parsed.values, ...where.values]) };
+}
+
+function deleteRow(request: PluginRendererOperationRequest): { changes: number } {
+  const input = requireInput(request.input);
+  const tableName = readRequiredString(input.table, "table", 512);
+  const connection = requireDatabase().connection;
+  const schema = readTableSchema(connection, tableName);
+  const locator = parseLocator(schema, input.locator);
+  const where = buildLocatorWhere(schema, locator);
+  const sql = "DELETE FROM " + quoteIdentifier(schema.summary.name) + " WHERE " + where.sql;
+  return { changes: runSingleRowMutation(connection, sql, where.values) };
+}
+
+function runSingleRowMutation(connection: Database, sql: string, values: unknown[]): number {
+  return connection.transaction(() => {
+    const changes = connection.prepare(sql).run(...values).changes;
+    if (changes === 0) {
+      throw codedError("NotFound", "The selected row no longer exists.");
+    }
+    if (changes !== 1) {
+      throw codedError("InvalidRequest", "The row locator matched more than one record.");
+    }
+    return changes;
+  })();
+}
+
+function readTableSummaries(connection: Database): TableSummary[] {
+  return connection.prepare("PRAGMA main.table_list").all().flatMap((value) => {
+    const row = requireRecord(value, "table_list row") as unknown as TableListRow;
+    if (typeof row.schema !== "string" || typeof row.name !== "string" || typeof row.type !== "string") {
+      throw new Error("SQLite table_list row is malformed.");
+    }
+    if (row.schema !== "main" || row.type !== "table" || row.name.startsWith("sqlite_")) {
+      return [];
+    }
+    return [{
+      name: row.name,
+      columnCount: integerNumber(row.ncol, "table column count"),
+      withoutRowid: integerNumber(row.wr, "without-rowid flag") === 1,
+      strict: integerNumber(row.strict, "strict flag") === 1
+    }];
+  }).sort((left, right) => left.name.localeCompare(right.name, "en-US", { sensitivity: "base" }));
+}
+
+function readTableSchema(connection: Database, tableName: string): TableSchema {
+  const summary = readTableSummaries(connection).find((table) => table.name === tableName);
+  if (!summary) {
+    throw codedError("InvalidRequest", "The requested table is not an editable user table.");
   }
-  const updateResult = requireDatabase().prepare(
-    "UPDATE " + tableName + " SET title = ?, note = ? WHERE id = ?"
-  ).run(inputResult.value.title, inputResult.value.note, idResult.value);
-  if (updateResult.changes === 0) {
-    return fail("NotFound", "Record was not found.");
+  const rows = connection.prepare("PRAGMA main.table_xinfo(" + quoteIdentifier(tableName) + ")").all();
+  const rawColumns = rows.map((value) => requireRecord(value, "table_xinfo row") as unknown as TableXinfoRow);
+  const primaryKeyCount = rawColumns.filter((column) => integerNumber(column.pk, "primary-key order") > 0).length;
+  const hasPrimaryKeyIndex = connection.prepare("PRAGMA main.index_list(" + quoteIdentifier(tableName) + ")").all().some((value) => {
+    const row = requireRecord(value, "index_list row") as unknown as TableIndexListRow;
+    return row.origin === "pk";
+  });
+  const columns = rawColumns.map((row): ColumnInfo => {
+    if (typeof row.name !== "string" || row.name.length === 0) {
+      throw new Error("SQLite table_xinfo row is malformed.");
+    }
+    const primaryKeyOrder = integerNumber(row.pk, "primary-key order");
+    const hiddenValue = integerNumber(row.hidden, "hidden flag");
+    const declaredType = typeof row.type === "string" ? row.type : "";
+    const defaultSql = row.dflt_value === null || row.dflt_value === undefined ? null : String(row.dflt_value);
+    const autoIntegerPrimaryKey = !summary.withoutRowid
+      && primaryKeyCount === 1
+      && primaryKeyOrder === 1
+      && declaredType.trim().toUpperCase() === "INTEGER"
+      && !hasPrimaryKeyIndex;
+    const generated = hiddenValue === 2 || hiddenValue === 3;
+    const hidden = hiddenValue === 1;
+    const insertable = !generated && !hidden;
+    const implicitNotNullPrimaryKey = primaryKeyOrder > 0
+      && (summary.withoutRowid || summary.strict || autoIntegerPrimaryKey);
+    const nullable = integerNumber(row.notnull, "not-null flag") === 0 && !implicitNotNullPrimaryKey;
+    return {
+      name: row.name,
+      declaredType,
+      affinity: sqliteAffinity(declaredType),
+      nullable,
+      defaultSql,
+      primaryKeyOrder,
+      generated,
+      hidden,
+      insertable,
+      requiredOnInsert: insertable && !nullable && defaultSql === null && !autoIntegerPrimaryKey,
+      autoIntegerPrimaryKey
+    };
+  });
+  const visibleColumns = columns.filter((column) => !column.hidden);
+  const writableColumns = columns.filter((column) => column.insertable);
+  return {
+    summary,
+    columns,
+    visibleColumns,
+    writableColumns,
+    locator: createLocatorSpec(summary, columns)
+  };
+}
+
+function createLocatorSpec(summary: TableSummary, columns: ColumnInfo[]): LocatorSpec | undefined {
+  if (!summary.withoutRowid) {
+    const names = new Set(columns.map((column) => column.name.toLowerCase()));
+    const rowidAlias = (["rowid", "_rowid_", "oid"] as const).find((name) => !names.has(name));
+    if (rowidAlias) {
+      return { kind: "rowid", columns: [rowidAlias], rowidAlias };
+    }
   }
-  const record = readRecord(idResult.value);
-  if (!record) {
-    throw new Error("Updated SQLite record could not be read.");
+  const primaryKeyColumns = columns
+    .filter((column) => column.primaryKeyOrder > 0)
+    .sort((left, right) => left.primaryKeyOrder - right.primaryKeyOrder);
+  if (primaryKeyColumns.length > 0 && primaryKeyColumns.every((column) => !column.nullable)) {
+    return { kind: "primaryKey", columns: primaryKeyColumns.map((column) => column.name) };
   }
-  return { record };
+  return undefined;
 }
 
-function deleteRecord(request: PluginRendererOperationRequest): NexusResult<never> | { deletedId: number; record: SqliteRecord } {
-  const idResult = readRecordId(request.input, "Delete");
-  if (!idResult.ok) {
-    return idResult;
+function locatorProjection(schema: TableSchema): string[] {
+  const spec = schema.locator;
+  if (!spec) {
+    return [];
   }
-  const record = readRecord(idResult.value);
-  if (!record) {
-    return fail("NotFound", "Record was not found.");
+  if (spec.kind === "rowid") {
+    return [spec.rowidAlias as string];
   }
-  requireDatabase().prepare("DELETE FROM " + tableName + " WHERE id = ?").run(idResult.value);
-  return { deletedId: idResult.value, record };
+  return spec.columns.map((column) => {
+    const identifier = quoteIdentifier(column);
+    return "CASE WHEN typeof(" + identifier + ") IN ('text', 'blob')"
+      + " AND length(CAST(" + identifier + " AS BLOB)) > " + String(maximumLocatorBytes)
+      + " THEN NULL ELSE " + identifier + " END";
+  });
 }
 
-function readRecord(id: number): SqliteRecord | undefined {
-  const row = requireDatabase().prepare(
-    "SELECT id, title, note, created_at AS createdAt FROM " + tableName + " WHERE id = ?"
-  ).get(id);
-  return row === undefined ? undefined : readRecordRow(row);
+function previewProjection(column: ColumnInfo): string[] {
+  const identifier = quoteIdentifier(column.name);
+  const storageType = "typeof(" + identifier + ")";
+  return [
+    storageType,
+    "CASE WHEN " + storageType + " = 'text' THEN length(" + identifier + ") ELSE NULL END",
+    "CASE WHEN " + storageType + " IN ('text', 'blob') THEN length(CAST(" + identifier + " AS BLOB)) ELSE NULL END",
+    "CASE " + storageType
+      + " WHEN 'text' THEN substr(" + identifier + ", 1, " + String(maximumTextPreviewBytes) + ")"
+      + " WHEN 'blob' THEN substr(" + identifier + ", 1, " + String(maximumBlobPreviewBytes) + ")"
+      + " ELSE " + identifier + " END"
+  ];
 }
 
-function readRecordRow(value: unknown): SqliteRecord {
-  const row = requireObject(value, "record row");
-  if (!Number.isSafeInteger(row.id) || typeof row.title !== "string" || typeof row.note !== "string" || typeof row.createdAt !== "string") {
-    throw new Error("SQLite record row is malformed.");
+function readTableRow(schema: TableSchema, rawRow: unknown[]): TableRow {
+  const locatorValueCount = schema.locator?.columns.length || 0;
+  const expectedValueCount = locatorValueCount + schema.visibleColumns.length * projectedValuesPerColumn;
+  if (rawRow.length !== expectedValueCount) {
+    throw new Error("SQLite table row has an unexpected column count.");
   }
-  return { id: row.id as number, title: row.title, note: row.note, createdAt: row.createdAt };
+  const cells = schema.visibleColumns.map((column, index) => {
+    const valueOffset = locatorValueCount + index * projectedValuesPerColumn;
+    return {
+      column: column.name,
+      value: serializeProjectedValue(
+        rawRow[valueOffset],
+        rawRow[valueOffset + 1],
+        rawRow[valueOffset + 2],
+        rawRow[valueOffset + 3]
+      )
+    };
+  });
+  const locator = createRowLocator(schema, rawRow.slice(0, locatorValueCount));
+  return { cells, ...(locator ? { locator } : {}) };
 }
 
-function readRecordInput(input: Record<string, unknown> | undefined, action: string): NexusResult<{ title: string; note: string }> {
-  if (!input) {
-    return fail("InvalidRequest", action + " input must be an object.");
+function createRowLocator(schema: TableSchema, rawLocatorValues: unknown[]): RowLocator | undefined {
+  const spec = schema.locator;
+  if (!spec) {
+    return undefined;
   }
-  const title = typeof input.title === "string" ? input.title.trim() : "";
-  const note = typeof input.note === "string" ? input.note.trim() : "";
-  if (title.length < 1 || title.length > 80) {
-    return fail("InvalidRequest", "Title must be 1 to 80 characters.");
+  if (spec.kind === "rowid") {
+    const value = serializeLocatorValue(rawLocatorValues[0]);
+    return value ? { kind: "rowid", values: [{ column: spec.columns[0], value }] } : undefined;
   }
-  if (note.length > 500) {
-    return fail("InvalidRequest", "Note must be 500 characters or fewer.");
+  const values: LocatorValue[] = [];
+  for (let index = 0; index < spec.columns.length; index += 1) {
+    const columnName = spec.columns[index];
+    const value = serializeLocatorValue(rawLocatorValues[index]);
+    if (!value) {
+      return undefined;
+    }
+    values.push({ column: columnName, value });
   }
-  return { ok: true, value: { title, note } };
+  return { kind: "primaryKey", values };
 }
 
-function readRecordId(input: Record<string, unknown> | undefined, action: string): NexusResult<number> {
-  if (!input) {
-    return fail("InvalidRequest", action + " input must be an object.");
+function serializeProjectedValue(
+  storageType: unknown,
+  characterLength: unknown,
+  byteLength: unknown,
+  preview: unknown
+): WireValue {
+  if (storageType === "null" && (preview === null || preview === undefined)) {
+    return { kind: "null" };
+  }
+  if (storageType === "integer" && typeof preview === "bigint") {
+    return { kind: "integer", value: preview.toString() };
+  }
+  if (storageType === "integer" && typeof preview === "number" && Number.isSafeInteger(preview)) {
+    return { kind: "integer", value: String(preview) };
+  }
+  if (storageType === "real" && typeof preview === "number" && Number.isFinite(preview)) {
+    return { kind: "real", value: preview };
+  }
+  if (storageType === "text" && typeof preview === "string") {
+    const totalCharacters = integerNumber(characterLength, "text character length");
+    const totalBytes = integerNumber(byteLength, "text byte length");
+    const boundedPreview = truncateUtf8(preview, maximumTextPreviewBytes);
+    return {
+      kind: "text",
+      value: boundedPreview,
+      length: totalCharacters,
+      truncated: Buffer.byteLength(boundedPreview, "utf8") < totalBytes
+    };
   }
-  const id = typeof input.id === "number"
-    ? input.id
-    : typeof input.id === "string"
-      ? Number(input.id.trim())
-      : Number.NaN;
-  if (!Number.isSafeInteger(id) || id < 1) {
-    return fail("InvalidRequest", action + " record id must be a positive integer.");
+  if (storageType === "blob" && Buffer.isBuffer(preview)) {
+    const totalBytes = integerNumber(byteLength, "BLOB byte length");
+    return {
+      kind: "blob",
+      hex: preview.toString("hex"),
+      byteLength: totalBytes,
+      truncated: preview.length < totalBytes
+    };
   }
-  return { ok: true, value: id };
+  throw new Error("SQLite returned malformed projected cell data.");
 }
 
-function requireDatabase(): Database {
-  if (!database) {
-    throw new Error("SQLite database is not initialized.");
+function truncateUtf8(value: string, maximumBytes: number): string {
+  if (Buffer.byteLength(value, "utf8") <= maximumBytes) {
+    return value;
+  }
+  const characters: string[] = [];
+  let byteLength = 0;
+  for (const character of value) {
+    const characterBytes = Buffer.byteLength(character, "utf8");
+    if (byteLength + characterBytes > maximumBytes) {
+      break;
+    }
+    characters.push(character);
+    byteLength += characterBytes;
+  }
+  return characters.join("");
+}
+
+function serializeLocatorValue(value: unknown): WireValue | undefined {
+  if (value === null || value === undefined) {
+    return undefined;
+  }
+  if (typeof value === "string" && (value.length > maximumLocatorBytes
+    || Buffer.byteLength(value, "utf8") > maximumLocatorBytes)) {
+    return undefined;
+  }
+  if (Buffer.isBuffer(value) && value.length > maximumLocatorBytes) {
+    return undefined;
+  }
+  if (typeof value === "string") {
+    return { kind: "text", value, length: value.length, truncated: false };
+  }
+  if (Buffer.isBuffer(value)) {
+    return { kind: "blob", hex: value.toString("hex"), byteLength: value.length, truncated: false };
+  }
+  if (typeof value === "bigint") {
+    return { kind: "integer", value: value.toString() };
+  }
+  if (typeof value === "number" && Number.isFinite(value)) {
+    return Number.isInteger(value)
+      ? { kind: "integer", value: String(value) }
+      : { kind: "real", value };
+  }
+  return undefined;
+}
+
+function parseMutations(schema: TableSchema, value: unknown, mode: "insert" | "update"): ParsedMutations {
+  const valuesRecord = requireRecord(value, "column values");
+  const knownColumns = new Map(schema.writableColumns.map((column) => [column.name, column]));
+  const columns: string[] = [];
+  const values: unknown[] = [];
+  let requestBytes = 0;
+  for (const key of Object.keys(valuesRecord)) {
+    const column = knownColumns.get(key);
+    if (!column) {
+      throw codedError("InvalidRequest", "Column is not writable or does not exist: " + key);
+    }
+    const mutation = readMutationValue(valuesRecord[key], key);
+    if (mutation.mode === "default" || mutation.mode === "unchanged") {
+      if (mode === "update" && mutation.mode === "default") {
+        throw codedError("InvalidRequest", "Default mode is not supported during update: " + key);
+      }
+      if (mode === "insert" && mutation.mode === "unchanged") {
+        throw codedError("InvalidRequest", "Unchanged mode is not supported during insert: " + key);
+      }
+      continue;
+    }
+    if (mutation.mode === "null") {
+      if (!column.nullable) {
+        throw codedError("InvalidRequest", "Column does not accept NULL: " + key);
+      }
+      columns.push(key);
+      values.push(null);
+      continue;
+    }
+    const converted = convertInputValue(column, mutation.value || "");
+    if (converted.byteLength > maximumFieldBytes) {
+      throw codedError("InvalidRequest", "Column value exceeds the 1 MiB limit: " + key);
+    }
+    requestBytes += converted.byteLength;
+    if (requestBytes > maximumRequestBytes) {
+      throw codedError("InvalidRequest", "Row values exceed the 4 MiB request limit.");
+    }
+    columns.push(key);
+    values.push(converted.value);
+  }
+  if (mode === "insert") {
+    for (const column of schema.writableColumns) {
+      if (column.requiredOnInsert && !columns.includes(column.name)) {
+        throw codedError("InvalidRequest", "A value is required for column: " + column.name);
+      }
+    }
+  }
+  return { columns, values };
+}
+
+function readMutationValue(value: unknown, columnName: string): MutationValue {
+  const record = requireRecord(value, "mutation for " + columnName);
+  if (record.mode !== "default" && record.mode !== "unchanged" && record.mode !== "null" && record.mode !== "value") {
+    throw codedError("InvalidRequest", "Column mutation mode is invalid: " + columnName);
+  }
+  if (record.mode === "value" && typeof record.value !== "string") {
+    throw codedError("InvalidRequest", "Column value must be text: " + columnName);
   }
-  return database;
+  return { mode: record.mode, ...(typeof record.value === "string" ? { value: record.value } : {}) };
 }
 
-function requireObject(value: unknown, label: string): Record<string, unknown> {
+function convertInputValue(column: ColumnInfo, source: string): ConvertedInputValue {
+  if (column.affinity === "blob") {
+    if (source.length > maximumBlobInputCharacters) {
+      throw codedError("InvalidRequest", "BLOB value exceeds the accepted encoded input size: " + column.name);
+    }
+    const normalized = source.replace(/\s+/g, "");
+    if (normalized.length > maximumFieldBytes * 2) {
+      throw codedError("InvalidRequest", "BLOB value exceeds the 1 MiB limit: " + column.name);
+    }
+    if (normalized.length % 2 !== 0 || !/^[0-9a-fA-F]*$/.test(normalized)) {
+      throw codedError("InvalidRequest", "BLOB columns require an even-length hexadecimal value: " + column.name);
+    }
+    const buffer = Buffer.from(normalized, "hex");
+    return { value: buffer, byteLength: buffer.length };
+  }
+  const sourceBytes = boundedUtf8ByteLength(source, maximumFieldBytes, "Column value exceeds the 1 MiB limit: " + column.name);
+  if (column.affinity === "integer") {
+    return { value: parseSqliteInteger(source, "Column " + column.name), byteLength: sourceBytes };
+  }
+  if (column.affinity === "real") {
+    const parsed = Number(source);
+    if (!source.trim() || !Number.isFinite(parsed)) {
+      throw codedError("InvalidRequest", "Column requires a finite number: " + column.name);
+    }
+    return { value: parsed, byteLength: sourceBytes };
+  }
+  if (column.affinity === "numeric") {
+    if (/^[+-]?\d+$/.test(source)) {
+      return { value: parseSqliteInteger(source, "Column " + column.name), byteLength: sourceBytes };
+    }
+    const parsed = Number(source);
+    return {
+      value: source.trim() && Number.isFinite(parsed) ? parsed : source,
+      byteLength: sourceBytes
+    };
+  }
+  return { value: source, byteLength: sourceBytes };
+}
+
+function boundedUtf8ByteLength(source: string, maximumBytes: number, message: string): number {
+  if (source.length > maximumBytes) {
+    throw codedError("InvalidRequest", message);
+  }
+  const byteLength = Buffer.byteLength(source, "utf8");
+  if (byteLength > maximumBytes) {
+    throw codedError("InvalidRequest", message);
+  }
+  return byteLength;
+}
+
+function parseSqliteInteger(source: string, label: string): bigint {
+  if (source.length > maximumSqliteIntegerCharacters || !/^[+-]?\d+$/.test(source)) {
+    throw codedError("InvalidRequest", label + " requires a signed 64-bit integer.");
+  }
+  const value = BigInt(source);
+  if (value < minimumSqliteInteger || value > maximumSqliteInteger) {
+    throw codedError("InvalidRequest", label + " is outside SQLite's signed 64-bit range.");
+  }
+  return value;
+}
+
+function parseLocator(schema: TableSchema, value: unknown): RowLocator {
+  const spec = schema.locator;
+  if (!spec) {
+    throw codedError("UnsupportedTable", "This table does not expose a stable row locator.");
+  }
+  const record = requireRecord(value, "row locator");
+  if (record.kind !== spec.kind || !Array.isArray(record.values) || record.values.length !== spec.columns.length) {
+    throw codedError("InvalidRequest", "Row locator does not match the current table.");
+  }
+  const values = record.values.map((entry, index): LocatorValue => {
+    const item = requireRecord(entry, "row locator value");
+    const expectedColumn = spec.columns[index];
+    if (item.column !== expectedColumn) {
+      throw codedError("InvalidRequest", "Row locator columns do not match the current table.");
+    }
+    return { column: expectedColumn, value: readWireValue(item.value) };
+  });
+  return { kind: spec.kind, values };
+}
+
+function readWireValue(value: unknown): WireValue {
+  const record = requireRecord(value, "wire value");
+  if (record.kind === "null") {
+    return { kind: "null" };
+  }
+  if (record.kind === "integer" && typeof record.value === "string") {
+    return { kind: "integer", value: parseSqliteInteger(record.value, "Row locator").toString() };
+  }
+  if (record.kind === "real" && typeof record.value === "number" && Number.isFinite(record.value)) {
+    return { kind: "real", value: record.value };
+  }
+  if (record.kind === "text" && typeof record.value === "string" && record.truncated === false
+    && record.value.length <= maximumLocatorBytes
+    && Buffer.byteLength(record.value, "utf8") <= maximumLocatorBytes) {
+    return { kind: "text", value: record.value, length: record.value.length, truncated: false };
+  }
+  if (record.kind === "blob" && typeof record.hex === "string" && record.truncated === false
+    && record.hex.length <= maximumLocatorBytes * 2
+    && record.hex.length % 2 === 0 && /^[0-9a-fA-F]*$/.test(record.hex)) {
+    return { kind: "blob", hex: record.hex, byteLength: record.hex.length / 2, truncated: false };
+  }
+  throw codedError("InvalidRequest", "Row locator contains an invalid value.");
+}
+
+function buildLocatorWhere(schema: TableSchema, locator: RowLocator): { sql: string; values: unknown[] } {
+  const spec = schema.locator;
+  if (!spec || locator.kind !== spec.kind) {
+    throw codedError("InvalidRequest", "Row locator does not match the current table.");
+  }
+  const expressions = locator.values.map((entry) => {
+    return spec.kind === "rowid"
+      ? (spec.rowidAlias as string) + " IS ?"
+      : quoteIdentifier(entry.column) + " IS ?";
+  });
+  return { sql: expressions.join(" AND "), values: locator.values.map((entry) => decodeWireValue(entry.value)) };
+}
+
+function decodeWireValue(value: WireValue): unknown {
+  if (value.kind === "null") {
+    return null;
+  }
+  if (value.kind === "integer") {
+    return BigInt(value.value);
+  }
+  if (value.kind === "real") {
+    return value.value;
+  }
+  if (value.kind === "text") {
+    return value.value;
+  }
+  return Buffer.from(value.hex, "hex");
+}
+
+function readCount(connection: Database, tableName: string): bigint {
+  const row = requireRecord(
+    connection.prepare("SELECT COUNT(*) AS count FROM " + quoteIdentifier(tableName)).get(),
+    "count row"
+  );
+  if (typeof row.count === "bigint") {
+    return row.count;
+  }
+  if (typeof row.count === "number" && Number.isSafeInteger(row.count) && row.count >= 0) {
+    return BigInt(row.count);
+  }
+  throw new Error("SQLite count row is malformed.");
+}
+
+function orderByClause(locator: LocatorSpec | undefined): string {
+  if (!locator) {
+    return "";
+  }
+  if (locator.kind === "rowid") {
+    return " ORDER BY " + locator.rowidAlias + " DESC";
+  }
+  return " ORDER BY " + locator.columns.map((column) => quoteIdentifier(column) + " ASC").join(", ");
+}
+
+function sqliteAffinity(declaredType: string): SqliteAffinity {
+  const normalized = declaredType.toUpperCase();
+  if (normalized.includes("INT")) {
+    return "integer";
+  }
+  if (normalized.includes("CHAR") || normalized.includes("CLOB") || normalized.includes("TEXT")) {
+    return "text";
+  }
+  if (!normalized || normalized.includes("BLOB")) {
+    return "blob";
+  }
+  if (normalized.includes("REAL") || normalized.includes("FLOA") || normalized.includes("DOUB")) {
+    return "real";
+  }
+  return "numeric";
+}
+
+function readPersistedDatabasePath(): string | undefined {
+  if (!fs.existsSync(stateFilePath)) {
+    return undefined;
+  }
+  try {
+    const parsed = JSON.parse(fs.readFileSync(stateFilePath, "utf8")) as Partial<PersistedState>;
+    if (parsed.schemaVersion !== 1 || typeof parsed.databasePath !== "string" || !path.isAbsolute(parsed.databasePath)) {
+      throw new Error("SQLite browser state is invalid.");
+    }
+    return path.resolve(parsed.databasePath);
+  } catch (error: unknown) {
+    const invalidPath = stateFilePath + ".invalid-" + String(Date.now());
+    try {
+      fs.renameSync(stateFilePath, invalidPath);
+    } catch {
+      try {
+        fs.rmSync(stateFilePath, { force: true });
+      } catch {
+        // A read-only state file must not prevent the safe default database fallback.
+      }
+    }
+    databaseNotice = "The saved database selection was invalid and has been reset: " + errorMessage(error);
+    return undefined;
+  }
+}
+
+function persistDatabasePath(filePath: string): void {
+  writeJsonAtomic(stateFilePath, { schemaVersion: 1, databasePath: path.resolve(filePath) } satisfies PersistedState);
+}
+
+function clearPersistedState(): void {
+  fs.rmSync(stateFilePath, { force: true });
+}
+
+function writeJsonAtomic(filePath: string, value: unknown): void {
+  const tempPath = filePath + "." + String(process.pid) + "." + String(Date.now()) + ".tmp";
+  fs.writeFileSync(tempPath, JSON.stringify(value, null, 2) + "\n", "utf8");
+  try {
+    fs.renameSync(tempPath, filePath);
+  } finally {
+    fs.rmSync(tempPath, { force: true });
+  }
+}
+
+function readPageSize(value: unknown): number {
+  const result = value === undefined ? 50 : Number(value);
+  if (!Number.isSafeInteger(result) || !allowedPageSizes.has(result)) {
+    throw codedError("InvalidRequest", "Page size must be 25, 50, or 100.");
+  }
+  return result;
+}
+
+function readOffset(value: unknown): number {
+  const result = value === undefined ? 0 : Number(value);
+  if (!Number.isSafeInteger(result) || result < 0 || result > 1_000_000_000) {
+    throw codedError("InvalidRequest", "Offset must be a non-negative integer no greater than 1000000000.");
+  }
+  return result;
+}
+
+function requireInput(value: Record<string, unknown> | undefined): Record<string, unknown> {
+  if (!value) {
+    throw codedError("InvalidRequest", "Operation input must be an object.");
+  }
+  return value;
+}
+
+function readRequiredString(value: unknown, label: string, maximumLength: number): string {
+  if (typeof value !== "string" || value.length < 1 || value.length > maximumLength) {
+    throw codedError("InvalidRequest", label + " must be a non-empty string.");
+  }
+  return value;
+}
+
+function requireRecord(value: unknown, label: string): Record<string, unknown> {
   if (!value || typeof value !== "object" || Array.isArray(value)) {
-    throw new Error("SQLite " + label + " is malformed.");
+    throw codedError("InvalidRequest", "SQLite " + label + " must be an object.");
   }
   return value as Record<string, unknown>;
 }
 
+function requireArrayRows(value: unknown[]): unknown[][] {
+  return value.map((row) => {
+    if (!Array.isArray(row)) {
+      throw new Error("SQLite raw row is malformed.");
+    }
+    return row;
+  });
+}
+
+function integerNumber(value: unknown, label: string): number {
+  const result = typeof value === "bigint" ? Number(value) : value;
+  if (typeof result !== "number" || !Number.isSafeInteger(result)) {
+    throw new Error("SQLite " + label + " is malformed.");
+  }
+  return result;
+}
+
+function quoteIdentifier(value: string): string {
+  return "\"" + value.replace(/\"/g, "\"\"") + "\"";
+}
+
+function requireDatabase(): ActiveDatabase {
+  if (!activeDatabase) {
+    throw codedError("DatabaseUnavailable", "SQLite database is not initialized.");
+  }
+  return activeDatabase;
+}
+
+function requireActivationContext(): PluginMainActivationContext {
+  if (!activationContext) {
+    throw codedError("DatabaseUnavailable", "Plugin activation context is unavailable.");
+  }
+  return activationContext;
+}
+
+function success<T>(value: T): NexusResult<T> {
+  return { ok: true, value };
+}
+
+function sqliteFailure(error: unknown): NexusResult<never> {
+  const code = errorCode(error);
+  if (code === "InvalidRequest" || code === "NotFound" || code === "UnsupportedTable"
+    || code === "Busy" || code === "DatabaseUnavailable") {
+    return fail(code, errorMessage(error));
+  }
+  if (code.startsWith("SQLITE_CONSTRAINT")) {
+    return fail("ConstraintViolation", errorMessage(error));
+  }
+  if (code === "SQLITE_READONLY" || code.startsWith("SQLITE_READONLY_")) {
+    return fail("SqliteReadOnly", errorMessage(error));
+  }
+  if (code === "SQLITE_BUSY" || code === "SQLITE_LOCKED" || code.startsWith("SQLITE_BUSY_") || code.startsWith("SQLITE_LOCKED_")) {
+    return fail("SqliteBusy", errorMessage(error));
+  }
+  if (code === "SQLITE_CORRUPT" || code === "SQLITE_NOTADB" || code.startsWith("SQLITE_CORRUPT_")) {
+    return fail("SqliteInvalidDatabase", errorMessage(error));
+  }
+  if (code === "ENOENT" || code === "EACCES" || code === "EPERM"
+    || code === "SQLITE_CANTOPEN" || code.startsWith("SQLITE_CANTOPEN_")
+    || code === "SQLITE_PERM" || code === "SQLITE_AUTH") {
+    return fail("SqliteOpenFailed", errorMessage(error));
+  }
+  return fail("SqliteOperationFailed", errorMessage(error));
+}
+
+function codedError(code: string, message: string): Error {
+  const error = new Error(message) as Error & { code: string };
+  error.code = code;
+  return error;
+}
+
+function errorCode(error: unknown): string {
+  return error && typeof error === "object" && typeof Reflect.get(error, "code") === "string"
+    ? String(Reflect.get(error, "code"))
+    : "";
+}
+
+function errorMessage(error: unknown): string {
+  return error instanceof Error ? error.message : String(error);
+}
+
 function fail<T = never>(code: string, message: string): NexusResult<T> {
   return { ok: false, error: { code, message } };
 }