nsa-sheets-db-builder 4.0.0

package/libs/db_ddl.ts

@@ -0,0 +1,316 @@
+/**
+ * DB DDL V2 - Schema provisioning (DDL) for Google Sheets databases
+ *
+ * Provides CREATE TABLE / SHOW TABLES / DESCRIBE / DROP TABLE / SYNC SCHEMA
+ * operations for Google Sheets, treating sheets as tables and row 1 as headers.
+ *
+ * Usage via clasp run:
+ *   clasp run ddlCreateSpreadsheet --params '[{"name":"my-db"}]'
+ *   clasp run ddlProvisionTables --params '[{"spreadsheetId":"...","tables":{...}}]'
+ *   clasp run ddlShowTables --params '[{"spreadsheetId":"..."}]'
+ *   clasp run ddlDescribeTable --params '[{"spreadsheetId":"...","table":"users"}]'
+ *   clasp run ddlDropTable --params '[{"spreadsheetId":"...","table":"users"}]'
+ *   clasp run ddlSyncSchema --params '[{"spreadsheetId":"...","tables":{...}}]'
+ */
+
+// Declare dependencies
+declare class GASLoggerV2 {
+  info(source: string, message: string, context: any): void;
+  warn(source: string, message: string, context: any): void;
+  debug(source: string, message: string, context: any): void;
+}
+
+// ── Constants ─────────────────────────────
+
+const DDL_SYS_TABLES_SHEET = '__sys__tables__';
+const DDL_SYS_TABLES_HEADERS = ['table_name', 'sheet_name', 'spreadsheet_id', 'created_at', 'column_count'];
+
+// ── Types ─────────────────────────────────
+
+interface DDLCreateSpreadsheetResult {
+  spreadsheetId: string;
+  url: string;
+  name: string;
+}
+
+interface DDLTableResult {
+  name: string;
+  sheetName: string;
+  spreadsheetId: string;
+  status: 'created' | 'exists' | 'skipped';
+  columns?: number;
+  reason?: string;
+}
+
+interface DDLProvisionResult {
+  tables: DDLTableResult[];
+}
+
+interface DDLShowTablesEntry {
+  name: string;
+  rows: number;
+  columns: number;
+}
+
+interface DDLDescribeResult {
+  table: string;
+  columns: string[];
+  rowCount: number;
+}
+
+interface DDLSyncResult {
+  created: { name: string; sheetName: string; columns: number }[];
+  existing: { name: string; sheetName: string }[];
+  drift: { name: string; sheetName: string; missing: string[]; extra: string[] }[];
+}
+
+// ── Core DDL Class ────────────────────────
+
+class DBDDLV2 {
+  private logger: GASLoggerV2 | null;
+
+  constructor(logger?: GASLoggerV2 | null) {
+    this.logger = logger || null;
+  }
+
+  /**
+   * Create a new Google Spreadsheet and initialize it with __sys__tables__
+   */
+  createSpreadsheet(name: string): DDLCreateSpreadsheetResult {
+    if (!name) throw new Error('Missing "name" parameter');
+
+    const ss = SpreadsheetApp.create(name);
+    const spreadsheetId = ss.getId();
+    const url = ss.getUrl();
+
+    // Initialize sys tables, then remove default Sheet1
+    this.ensureSysTablesSheet(ss);
+    const defaultSheet = ss.getSheetByName('Sheet1');
+    if (defaultSheet) {
+      ss.deleteSheet(defaultSheet);
+    }
+
+    this.logger?.info('DBDDLV2.createSpreadsheet', `Created spreadsheet "${name}"`, { spreadsheetId });
+
+    return { spreadsheetId, url, name };
+  }
+
+  /**
+   * Provision tables from a DBConfigV2-shaped tables object.
+   * Creates sheets with headers + __sys__tables__ entries for each table.
+   */
+  provisionTables(spreadsheetId: string, tables: Record<string, any>): DDLProvisionResult {
+    if (!spreadsheetId) throw new Error('Missing "spreadsheetId" parameter');
+    if (!tables || typeof tables !== 'object') throw new Error('Missing or invalid "tables" parameter');
+
+    const ss = SpreadsheetApp.openById(spreadsheetId);
+    this.ensureSysTablesSheet(ss);
+
+    const results: DDLTableResult[] = [];
+
+    for (const [tableName, tableConfig] of Object.entries(tables)) {
+      const sheetName = tableConfig.sheetName || tableName;
+      const schema = tableConfig.schema;
+
+      if (!schema) {
+        this.logger?.warn('DBDDLV2.provisionTables', `Table "${tableName}" has no schema, skipping`, {});
+        results.push({ name: tableName, sheetName, spreadsheetId, status: 'skipped', reason: 'no schema' });
+        continue;
+      }
+
+      let sheet = ss.getSheetByName(sheetName);
+      if (sheet) {
+        this.logger?.info('DBDDLV2.provisionTables', `Sheet "${sheetName}" already exists, skipping`, {});
+        results.push({ name: tableName, sheetName, spreadsheetId, status: 'exists' });
+        continue;
+      }
+
+      // Create sheet with headers
+      sheet = ss.insertSheet(sheetName);
+      const headers = Object.keys(schema);
+      sheet.getRange(1, 1, 1, headers.length).setValues([headers]);
+      sheet.getRange(1, 1, 1, headers.length).setFontWeight('bold');
+      sheet.setFrozenRows(1);
+
+      // Register in __sys__tables__
+      this.registerInSysTables(ss, tableName, sheetName, spreadsheetId, headers.length);
+
+      this.logger?.info('DBDDLV2.provisionTables', `Created sheet "${sheetName}" with ${headers.length} columns`, {});
+      results.push({ name: tableName, sheetName, spreadsheetId, status: 'created', columns: headers.length });
+    }
+
+    return { tables: results };
+  }
+
+  /**
+   * List all sheets in a spreadsheet with row/column counts
+   */
+  showTables(spreadsheetId: string): { tables: DDLShowTablesEntry[] } {
+    if (!spreadsheetId) throw new Error('Missing "spreadsheetId" parameter');
+
+    const ss = SpreadsheetApp.openById(spreadsheetId);
+    const sheets = ss.getSheets();
+
+    const tables = sheets.map(sheet => {
+      const name = sheet.getName();
+      const rows = Math.max(0, sheet.getLastRow() - 1);
+      const columns = sheet.getLastColumn();
+      return { name, rows, columns };
+    });
+
+    return { tables };
+  }
+
+  /**
+   * Describe a specific table — returns headers and row count
+   */
+  describeTable(spreadsheetId: string, table: string): DDLDescribeResult {
+    if (!spreadsheetId) throw new Error('Missing "spreadsheetId" parameter');
+    if (!table) throw new Error('Missing "table" parameter');
+
+    const ss = SpreadsheetApp.openById(spreadsheetId);
+    const sheet = ss.getSheetByName(table);
+
+    if (!sheet) {
+      throw new Error(`Sheet "${table}" not found`);
+    }
+
+    const lastCol = sheet.getLastColumn();
+    if (lastCol === 0) {
+      return { table, columns: [], rowCount: 0 };
+    }
+
+    const headers = sheet.getRange(1, 1, 1, lastCol).getValues()[0].map(String);
+    const rowCount = Math.max(0, sheet.getLastRow() - 1);
+
+    return { table, columns: headers, rowCount };
+  }
+
+  /**
+   * Drop a table (delete the sheet) and unregister from __sys__tables__
+   */
+  dropTable(spreadsheetId: string, table: string): { dropped: string } {
+    if (!spreadsheetId) throw new Error('Missing "spreadsheetId" parameter');
+    if (!table) throw new Error('Missing "table" parameter');
+
+    if (table === DDL_SYS_TABLES_SHEET) {
+      throw new Error('Cannot drop system metadata sheet');
+    }
+
+    const ss = SpreadsheetApp.openById(spreadsheetId);
+    const sheet = ss.getSheetByName(table);
+
+    if (!sheet) {
+      throw new Error(`Sheet "${table}" not found`);
+    }
+
+    this.unregisterFromSysTables(ss, table);
+    ss.deleteSheet(sheet);
+
+    this.logger?.info('DBDDLV2.dropTable', `Dropped sheet "${table}"`, { spreadsheetId });
+
+    return { dropped: table };
+  }
+
+  /**
+   * Sync schema — provisions missing tables, reports drift on existing ones
+   */
+  syncSchema(spreadsheetId: string, tables: Record<string, any>): DDLSyncResult {
+    if (!spreadsheetId) throw new Error('Missing "spreadsheetId" parameter');
+    if (!tables || typeof tables !== 'object') throw new Error('Missing or invalid "tables" parameter');
+
+    const ss = SpreadsheetApp.openById(spreadsheetId);
+    this.ensureSysTablesSheet(ss);
+
+    const created: DDLSyncResult['created'] = [];
+    const existing: DDLSyncResult['existing'] = [];
+    const drift: DDLSyncResult['drift'] = [];
+
+    for (const [tableName, tableConfig] of Object.entries(tables)) {
+      const sheetName = tableConfig.sheetName || tableName;
+      const schema = tableConfig.schema;
+      if (!schema) continue;
+
+      const expectedHeaders = Object.keys(schema);
+      const sheet = ss.getSheetByName(sheetName);
+
+      if (!sheet) {
+        // Create missing sheet
+        const newSheet = ss.insertSheet(sheetName);
+        newSheet.getRange(1, 1, 1, expectedHeaders.length).setValues([expectedHeaders]);
+        newSheet.getRange(1, 1, 1, expectedHeaders.length).setFontWeight('bold');
+        newSheet.setFrozenRows(1);
+        this.registerInSysTables(ss, tableName, sheetName, spreadsheetId, expectedHeaders.length);
+
+        created.push({ name: tableName, sheetName, columns: expectedHeaders.length });
+        continue;
+      }
+
+      // Sheet exists — check for drift
+      const lastCol = sheet.getLastColumn();
+      const actualHeaders = lastCol > 0
+        ? sheet.getRange(1, 1, 1, lastCol).getValues()[0].map(String)
+        : [];
+
+      const missing = expectedHeaders.filter(h => !actualHeaders.includes(h));
+      const extra = actualHeaders.filter(h => !expectedHeaders.includes(h));
+
+      if (missing.length > 0 || extra.length > 0) {
+        drift.push({ name: tableName, sheetName, missing, extra });
+      } else {
+        existing.push({ name: tableName, sheetName });
+      }
+    }
+
+    return { created, existing, drift };
+  }
+
+  // ── Internal helpers ──────────────────────
+
+  private ensureSysTablesSheet(ss: GoogleAppsScript.Spreadsheet.Spreadsheet): GoogleAppsScript.Spreadsheet.Sheet {
+    let sheet = ss.getSheetByName(DDL_SYS_TABLES_SHEET);
+    if (sheet) return sheet;
+
+    sheet = ss.insertSheet(DDL_SYS_TABLES_SHEET);
+    sheet.getRange(1, 1, 1, DDL_SYS_TABLES_HEADERS.length).setValues([DDL_SYS_TABLES_HEADERS]);
+    sheet.getRange(1, 1, 1, DDL_SYS_TABLES_HEADERS.length).setFontWeight('bold');
+    sheet.setFrozenRows(1);
+
+    this.logger?.info('DBDDLV2.ensureSysTablesSheet', 'Created __sys__tables__ metadata sheet', {});
+
+    return sheet;
+  }
+
+  private registerInSysTables(
+    ss: GoogleAppsScript.Spreadsheet.Spreadsheet,
+    tableName: string,
+    sheetName: string,
+    spreadsheetId: string,
+    columnCount: number
+  ): void {
+    const sysSheet = ss.getSheetByName(DDL_SYS_TABLES_SHEET);
+    if (!sysSheet) return;
+
+    const row = [tableName, sheetName, spreadsheetId, new Date().toISOString(), columnCount];
+    sysSheet.appendRow(row);
+
+    this.logger?.info('DBDDLV2.registerInSysTables', `Registered "${tableName}" in __sys__tables__`, {});
+  }
+
+  private unregisterFromSysTables(
+    ss: GoogleAppsScript.Spreadsheet.Spreadsheet,
+    tableName: string
+  ): void {
+    const sysSheet = ss.getSheetByName(DDL_SYS_TABLES_SHEET);
+    if (!sysSheet) return;
+
+    const data = sysSheet.getDataRange().getValues();
+    for (let i = data.length - 1; i >= 1; i--) {
+      if (data[i][0] === tableName) {
+        sysSheet.deleteRow(i + 1);
+        this.logger?.info('DBDDLV2.unregisterFromSysTables', `Removed "${tableName}" from __sys__tables__`, {});
+        return;
+      }
+    }
+  }
+}

package/libs/libraries.json

@@ -0,0 +1,56 @@
+{
+  "libraries": {
+    "spreadsheets_db": {
+      "file": "spreadsheets_db.ts",
+      "description": "Database abstraction layer for Google Sheets",
+      "version": "2.0.0",
+      "order": 0,
+      "required": true,
+      "source": "local"
+    },
+    "gaslogger": {
+      "file": "gaslogger.ts",
+      "description": "Structured logging utility",
+      "version": "1.0.0",
+      "order": 1,
+      "required": false,
+      "dependsOn": ["gaserror"],
+      "source": "common"
+    },
+    "gaserror": {
+      "file": "gaserror.ts",
+      "description": "Error handling for Google Apps Script",
+      "version": "1.0.0",
+      "order": 2,
+      "required": false,
+      "dependsOn": [],
+      "source": "common"
+    },
+    "gas_response_helper": {
+      "file": "gas_response_helper.ts",
+      "description": "API response formatting helper",
+      "version": "1.0.0",
+      "order": 3,
+      "required": false,
+      "dependsOn": [],
+      "source": "common"
+    },
+    "db_ddl": {
+      "file": "db_ddl.ts",
+      "description": "Schema provisioning (DDL) for Google Sheets databases",
+      "version": "2.0.0",
+      "order": 5,
+      "required": true,
+      "source": "local"
+    },
+    "alasql": {
+      "file": "alasql.js",
+      "description": "SQL query engine (native JS)",
+      "version": "1.0.0",
+      "order": 900,
+      "native": true,
+      "required": false,
+      "source": "local"
+    }
+  }
+}