nsa-sheets-db-builder 4.0.0

package/scripts/show.mjs

@@ -0,0 +1,37 @@
+#!/usr/bin/env node
+
+/**
+ * Show tables in data spreadsheets.
+ *
+ * Usage:
+ *   node scripts/show.mjs --db <name> [--env <env>] [--instance <type>]
+ */
+
+import { parseArgs, requireDb, loadDbConfig, getEnvConfig, getDistDirForInstance, claspRun, loadTables, requireDataSpreadsheet, requireInstance, ensureAuthenticated } from './lib/utils.mjs';
+
+const args = parseArgs();
+const dbName = requireDb(args, 'show.mjs');
+const config = loadDbConfig(dbName);
+const { env, envConfig } = getEnvConfig(config, args.env);
+const instance = requireInstance(args, envConfig);
+const distDir = getDistDirForInstance(dbName, instance.type);
+
+const tables = loadTables(dbName);
+const spreadsheetId = requireDataSpreadsheet(tables, dbName);
+
+// Auth enforcement
+const userProfile = await ensureAuthenticated(dbName, args, envConfig, env);
+
+console.log(`Showing tables for ${dbName} (${env}, ${instance.type})...`);
+console.log(`  Data spreadsheet: ${spreadsheetId}`);
+
+const result = claspRun(distDir, 'ddlShowTables', [{ spreadsheetId }], { userProfile });
+
+if (Array.isArray(result)) {
+  console.log(`\nTables (${result.length}):`);
+  for (const table of result) {
+    console.log(`  - ${table}`);
+  }
+} else {
+  console.log('\nResult:', JSON.stringify(result, null, 2));
+}

package/scripts/sync.mjs

@@ -0,0 +1,35 @@
+#!/usr/bin/env node
+
+/**
+ * Sync schema — detect drift between tables.json and the live data spreadsheet.
+ *
+ * Usage:
+ *   node scripts/sync.mjs --db <name> [--env <env>] [--instance <type>]
+ */
+
+import { parseArgs, requireDb, loadDbConfig, getEnvConfig, getDistDirForInstance, claspRun, loadTables, requireDataSpreadsheet, requireInstance, ensureAuthenticated } from './lib/utils.mjs';
+
+const args = parseArgs();
+const dbName = requireDb(args, 'sync.mjs');
+const config = loadDbConfig(dbName);
+const { env, envConfig } = getEnvConfig(config, args.env);
+const instance = requireInstance(args, envConfig);
+const distDir = getDistDirForInstance(dbName, instance.type);
+
+const tables = loadTables(dbName);
+const spreadsheetId = requireDataSpreadsheet(tables, dbName);
+const tableNames = Object.keys(tables);
+
+// Auth enforcement
+const userProfile = await ensureAuthenticated(dbName, args, envConfig, env);
+
+console.log(`Syncing schema for ${dbName} (${env}, ${instance.type})...`);
+console.log(`  Tables in schema: ${tableNames.join(', ')}`);
+console.log(`  Data spreadsheet: ${spreadsheetId}`);
+
+const result = claspRun(distDir, 'ddlSyncSchema', [{
+  spreadsheetId,
+  tables
+}], { userProfile });
+
+console.log('\nResult:', JSON.stringify(result, null, 2));

package/scripts/whoami.mjs

@@ -0,0 +1,36 @@
+#!/usr/bin/env node
+
+/**
+ * Check current Google account for a DB project.
+ *
+ * Usage:
+ *   node scripts/whoami.mjs --db <name> [--env <env>]
+ *
+ * Shows the logged-in account for the DB's clasp user profile.
+ */
+
+import { parseArgs, requireDb, loadDbConfig, getEnvConfig, getClaspUserProfile, hasClaspProfile, getAccountEmail } from './lib/utils.mjs';
+
+const args = parseArgs();
+const dbName = requireDb(args, 'whoami.mjs');
+const config = loadDbConfig(dbName);
+const { env } = getEnvConfig(config, args.env);
+
+const profile = getClaspUserProfile(dbName, env);
+
+if (!hasClaspProfile(profile)) {
+  console.log(`No credentials found for profile "${profile}".`);
+  console.log(`Run: npm run login -- --db ${dbName} --env ${env}`);
+  process.exit(1);
+}
+
+const email = await getAccountEmail(profile);
+
+if (email) {
+  console.log(`Logged in as: ${email}`);
+  console.log(`  Profile: ${profile}`);
+  console.log(`  Environment: ${env}`);
+} else {
+  console.log(`Profile "${profile}" exists but could not verify account.`);
+  console.log(`Token may be expired. Run: npm run login -- --db ${dbName} --env ${env}`);
+}

package/src/api/ddl-handler-entry.ts

@@ -0,0 +1,136 @@
+// ========================================
+// DDL Handler — Entry Points (generic, schema-agnostic)
+//
+// These functions run in the shared DDL handler (one per Google account).
+// They only need DriveApp + SpreadsheetApp — no PropertiesService,
+// CacheService, ScriptApp, or per-instance config.
+//
+// Excluded (stay in src/api/ddl.ts for DB scripts):
+//   ddlCacheSchema, ddlGetCachedSchema, ddlInvalidateCache, ddlRefreshCache
+//   ddlSetApiKey, ddlGetApiKey, ddlRotateApiKey
+//   ddlSetupCacheTrigger, ddlRemoveCacheTrigger, ddlRefreshCacheTrigger
+// ========================================
+
+// ── Drive Folder Management ─────────────
+
+function ddlCreateDriveFolder(params: { name: string; parentFolderId?: string }): any {
+  const folderName = params.name;
+  let folder: GoogleAppsScript.Drive.Folder;
+
+  if (params.parentFolderId) {
+    const parent = DriveApp.getFolderById(params.parentFolderId);
+    // Check if folder already exists
+    const existing = parent.getFoldersByName(folderName);
+    if (existing.hasNext()) {
+      folder = existing.next();
+    } else {
+      folder = parent.createFolder(folderName);
+    }
+  } else {
+    folder = DriveApp.createFolder(folderName);
+  }
+
+  return {
+    folderId: folder.getId(),
+    folderName: folder.getName(),
+    folderUrl: folder.getUrl()
+  };
+}
+
+// ── Setup: Create folder + system spreadsheet ──
+
+function ddlSetup(params: { name: string; driveFolderId?: string }): any {
+  const logger = getLogger();
+  const ddl = getDDL();
+  const dbName = params.name;
+
+  // 1. Create or get Drive folder
+  let folderId = params.driveFolderId;
+  let folderResult: any = null;
+
+  if (!folderId) {
+    folderResult = ddlCreateDriveFolder({ name: dbName });
+    folderId = folderResult.folderId;
+    logger.info('ddlSetup', `Created Drive folder "${dbName}"`, { folderId });
+  }
+
+  const folder = DriveApp.getFolderById(folderId);
+
+  // 2. Create system spreadsheet inside the folder
+  const sysName = `${dbName}__system`;
+  const sysResult = ddl.createSpreadsheet(sysName);
+  const sysFile = DriveApp.getFileById(sysResult.spreadsheetId);
+  folder.addFile(sysFile);
+  // Remove from root if it was created there
+  const rootFolder = DriveApp.getRootFolder();
+  rootFolder.removeFile(sysFile);
+
+  logger.info('ddlSetup', `Created system spreadsheet "${sysName}"`, { spreadsheetId: sysResult.spreadsheetId });
+
+  return {
+    folderId: folderId,
+    folderUrl: folderResult?.folderUrl || folder.getUrl(),
+    systemSpreadsheetId: sysResult.spreadsheetId,
+    systemSpreadsheetUrl: sysResult.url
+  };
+}
+
+// ── Data Spreadsheet Creation ───────────
+
+function ddlCreateDataSpreadsheet(params: { name: string; folderId: string }): any {
+  const ddlName = params.name;
+  const ss = SpreadsheetApp.create(ddlName);
+  const spreadsheetId = ss.getId();
+
+  // Move into the Drive folder
+  const folder = DriveApp.getFolderById(params.folderId);
+  const file = DriveApp.getFileById(spreadsheetId);
+  folder.addFile(file);
+  DriveApp.getRootFolder().removeFile(file);
+
+  // Remove default Sheet1
+  const defaultSheet = ss.getSheetByName('Sheet1');
+  if (defaultSheet && ss.getSheets().length > 1) {
+    ss.deleteSheet(defaultSheet);
+  }
+
+  return {
+    spreadsheetId: spreadsheetId,
+    url: ss.getUrl(),
+    name: ddlName
+  };
+}
+
+// ── Legacy single-spreadsheet creation ──
+
+function ddlCreateSpreadsheet(params: { name: string }): any {
+  return getDDL().createSpreadsheet(params.name);
+}
+
+// ── Table Provisioning ──────────────────
+
+function ddlProvisionTables(params: { spreadsheetId: string; tables: Record<string, any> }): any {
+  return getDDL().provisionTables(params.spreadsheetId, params.tables);
+}
+
+// ── Table Inspection ────────────────────
+
+function ddlShowTables(params: { spreadsheetId: string }): any {
+  return getDDL().showTables(params.spreadsheetId);
+}
+
+function ddlDescribeTable(params: { spreadsheetId: string; table: string }): any {
+  return getDDL().describeTable(params.spreadsheetId, params.table);
+}
+
+// ── Table Deletion ──────────────────────
+
+function ddlDropTable(params: { spreadsheetId: string; table: string }): any {
+  return getDDL().dropTable(params.spreadsheetId, params.table);
+}
+
+// ── Schema Sync ─────────────────────────
+
+function ddlSyncSchema(params: { spreadsheetId: string; tables: Record<string, any> }): any {
+  return getDDL().syncSchema(params.spreadsheetId, params.tables);
+}

package/src/api/ddl.ts

@@ -0,0 +1,321 @@
+// ========================================
+// DDL Entry Points — thin wrappers for clasp run
+//
+// Architecture:
+//   - System spreadsheet: holds __sys__tables__ metadata (separate from data)
+//   - Data spreadsheets: hold actual tables (can be multiple per DB)
+//   - Drive folder: organizes all spreadsheets for a DB+env
+//   - CacheService: caches schema for fast access between refreshes
+//
+// Usage:
+//   clasp run ddlSetup --params '[{"name":"my-db"}]'
+//   clasp run ddlProvisionTables --params '[{"systemSpreadsheetId":"...","tables":{...}}]'
+//   clasp run ddlShowTables --params '[{"systemSpreadsheetId":"..."}]'
+//   clasp run ddlDescribeTable --params '[{"systemSpreadsheetId":"...","table":"users"}]'
+//   clasp run ddlDropTable --params '[{"systemSpreadsheetId":"...","table":"users"}]'
+//   clasp run ddlSyncSchema --params '[{"systemSpreadsheetId":"...","tables":{...}}]'
+// ========================================
+
+const CACHE_TTL_SECONDS = 3600; // 1 hour
+const CACHE_KEY_PREFIX = 'ddl_schema_';
+
+function getDDL(): DBDDLV2 {
+  return new DBDDLV2(getLogger());
+}
+
+// ── Drive Folder Management ─────────────
+
+function ddlCreateDriveFolder(params: { name: string; parentFolderId?: string }): any {
+  const folderName = params.name;
+  let folder: GoogleAppsScript.Drive.Folder;
+
+  if (params.parentFolderId) {
+    const parent = DriveApp.getFolderById(params.parentFolderId);
+    // Check if folder already exists
+    const existing = parent.getFoldersByName(folderName);
+    if (existing.hasNext()) {
+      folder = existing.next();
+    } else {
+      folder = parent.createFolder(folderName);
+    }
+  } else {
+    folder = DriveApp.createFolder(folderName);
+  }
+
+  return {
+    folderId: folder.getId(),
+    folderName: folder.getName(),
+    folderUrl: folder.getUrl()
+  };
+}
+
+// ── Setup: Create folder + system spreadsheet ──
+
+function ddlSetup(params: { name: string; driveFolderId?: string }): any {
+  const logger = getLogger();
+  const ddl = getDDL();
+  const dbName = params.name;
+
+  // 1. Create or get Drive folder
+  let folderId = params.driveFolderId;
+  let folderResult: any = null;
+
+  if (!folderId) {
+    folderResult = ddlCreateDriveFolder({ name: dbName });
+    folderId = folderResult.folderId;
+    logger.info('ddlSetup', `Created Drive folder "${dbName}"`, { folderId });
+  }
+
+  const folder = DriveApp.getFolderById(folderId);
+
+  // 2. Create system spreadsheet inside the folder
+  const sysName = `${dbName}__system`;
+  const sysResult = ddl.createSpreadsheet(sysName);
+  const sysFile = DriveApp.getFileById(sysResult.spreadsheetId);
+  folder.addFile(sysFile);
+  // Remove from root if it was created there
+  const rootFolder = DriveApp.getRootFolder();
+  rootFolder.removeFile(sysFile);
+
+  logger.info('ddlSetup', `Created system spreadsheet "${sysName}"`, { spreadsheetId: sysResult.spreadsheetId });
+
+  // 3. Set up cache refresh trigger
+  const triggerResult = ddlSetupCacheTrigger({ intervalHours: 1 });
+
+  return {
+    folderId: folderId,
+    folderUrl: folderResult?.folderUrl || folder.getUrl(),
+    systemSpreadsheetId: sysResult.spreadsheetId,
+    systemSpreadsheetUrl: sysResult.url,
+    trigger: triggerResult
+  };
+}
+
+// ── Data Spreadsheet Creation ───────────
+
+function ddlCreateDataSpreadsheet(params: { name: string; folderId: string }): any {
+  const ddlName = params.name;
+  const ss = SpreadsheetApp.create(ddlName);
+  const spreadsheetId = ss.getId();
+
+  // Move into the Drive folder
+  const folder = DriveApp.getFolderById(params.folderId);
+  const file = DriveApp.getFileById(spreadsheetId);
+  folder.addFile(file);
+  DriveApp.getRootFolder().removeFile(file);
+
+  // Remove default Sheet1
+  const defaultSheet = ss.getSheetByName('Sheet1');
+  if (defaultSheet && ss.getSheets().length > 1) {
+    ss.deleteSheet(defaultSheet);
+  }
+
+  return {
+    spreadsheetId: spreadsheetId,
+    url: ss.getUrl(),
+    name: ddlName
+  };
+}
+
+// ── clasp run entry points (legacy — single spreadsheet) ──
+
+function ddlCreateSpreadsheet(params: { name: string }): any {
+  return getDDL().createSpreadsheet(params.name);
+}
+
+function ddlProvisionTables(params: { spreadsheetId: string; tables: Record<string, any> }): any {
+  const result = getDDL().provisionTables(params.spreadsheetId, params.tables);
+  // Cache the schema after provisioning
+  ddlCacheSchema({ tables: params.tables });
+  return result;
+}
+
+function ddlShowTables(params: { spreadsheetId: string }): any {
+  return getDDL().showTables(params.spreadsheetId);
+}
+
+function ddlDescribeTable(params: { spreadsheetId: string; table: string }): any {
+  return getDDL().describeTable(params.spreadsheetId, params.table);
+}
+
+function ddlDropTable(params: { spreadsheetId: string; table: string }): any {
+  return getDDL().dropTable(params.spreadsheetId, params.table);
+}
+
+function ddlSyncSchema(params: { spreadsheetId: string; tables: Record<string, any> }): any {
+  const result = getDDL().syncSchema(params.spreadsheetId, params.tables);
+  // Update cache after sync
+  ddlCacheSchema({ tables: params.tables });
+  return result;
+}
+
+// ── Schema Caching (CacheService) ───────
+
+function ddlCacheSchema(params: { tables: Record<string, any> }): any {
+  const cache = CacheService.getScriptCache();
+  const tableNames = Object.keys(params.tables);
+
+  // Cache each table's schema individually for granular access
+  for (const [tableName, tableConfig] of Object.entries(params.tables)) {
+    const cacheKey = CACHE_KEY_PREFIX + tableName;
+    cache.put(cacheKey, JSON.stringify(tableConfig), CACHE_TTL_SECONDS);
+  }
+
+  // Cache the full table list
+  cache.put(CACHE_KEY_PREFIX + '__index__', JSON.stringify(tableNames), CACHE_TTL_SECONDS);
+
+  return { status: 'ok', cached: tableNames.length, ttlSeconds: CACHE_TTL_SECONDS };
+}
+
+function ddlGetCachedSchema(params?: { table?: string }): any {
+  const cache = CacheService.getScriptCache();
+
+  if (params?.table) {
+    const cached = cache.get(CACHE_KEY_PREFIX + params.table);
+    if (!cached) return { status: 'miss', table: params.table };
+    return { status: 'hit', table: params.table, schema: JSON.parse(cached) };
+  }
+
+  // Return full index
+  const index = cache.get(CACHE_KEY_PREFIX + '__index__');
+  if (!index) return { status: 'miss' };
+
+  const tableNames = JSON.parse(index);
+  const schemas: Record<string, any> = {};
+  for (const name of tableNames) {
+    const cached = cache.get(CACHE_KEY_PREFIX + name);
+    if (cached) schemas[name] = JSON.parse(cached);
+  }
+
+  return { status: 'hit', tables: schemas };
+}
+
+function ddlInvalidateCache(): any {
+  const cache = CacheService.getScriptCache();
+  const index = cache.get(CACHE_KEY_PREFIX + '__index__');
+
+  if (index) {
+    const tableNames = JSON.parse(index);
+    for (const name of tableNames) {
+      cache.remove(CACHE_KEY_PREFIX + name);
+    }
+    cache.remove(CACHE_KEY_PREFIX + '__index__');
+    return { status: 'ok', invalidated: tableNames.length };
+  }
+
+  return { status: 'ok', invalidated: 0 };
+}
+
+// ── API Key Management (stored in Script Properties) ──
+
+function ddlSetApiKey(params: { key: string }): any {
+  if (!params.key) throw new Error('Missing "key" parameter');
+  PropertiesService.getScriptProperties().setProperty('DDL_API_KEY', params.key);
+  return { status: 'ok', message: 'DDL API key set' };
+}
+
+function ddlGetApiKey(): any {
+  const key = PropertiesService.getScriptProperties().getProperty('DDL_API_KEY');
+  return { hasKey: !!key, keyPrefix: key ? key.substring(0, 4) + '...' : null };
+}
+
+function ddlRotateApiKey(): any {
+  const newKey = Utilities.getUuid().replace(/-/g, '');
+  PropertiesService.getScriptProperties().setProperty('DDL_API_KEY', newKey);
+  return { status: 'ok', key: newKey };
+}
+
+// ── Cache Refresh (refreshes __sys__tables__ + CacheService) ──
+
+function ddlRefreshCache(params?: { systemSpreadsheetId?: string }): any {
+  const ssId = params?.systemSpreadsheetId || DEPLOYER_CONFIG.spreadsheetId;
+  if (!ssId) throw new Error('No systemSpreadsheetId provided or configured');
+
+  const ss = SpreadsheetApp.openById(ssId);
+
+  // Rebuild __sys__tables__ from live sheets
+  const sysSheet = ss.getSheetByName('__sys__tables__');
+  if (!sysSheet) return { status: 'skipped', reason: 'no __sys__tables__ sheet' };
+
+  // Read existing sys table entries to get spreadsheet IDs
+  const data = sysSheet.getDataRange().getValues();
+  const spreadsheetIds = new Set<string>();
+  for (let i = 1; i < data.length; i++) {
+    if (data[i][2]) spreadsheetIds.add(String(data[i][2]));
+  }
+
+  // Clear and rebuild from all known spreadsheets
+  const lastRow = sysSheet.getLastRow();
+  if (lastRow > 1) {
+    sysSheet.getRange(2, 1, lastRow - 1, sysSheet.getLastColumn()).clearContent();
+  }
+
+  let count = 0;
+  for (const sid of spreadsheetIds) {
+    try {
+      const dataSs = SpreadsheetApp.openById(sid);
+      for (const sheet of dataSs.getSheets()) {
+        const name = sheet.getName();
+        if (name.startsWith('__sys__')) continue;
+        const cols = sheet.getLastColumn();
+        sysSheet.appendRow([name, name, sid, new Date().toISOString(), cols]);
+        count++;
+      }
+    } catch (e) {
+      // Skip inaccessible spreadsheets
+    }
+  }
+
+  // Also refresh CacheService if DB_SCHEMA is available
+  if (typeof DB_SCHEMA !== 'undefined') {
+    ddlCacheSchema({ tables: DB_SCHEMA });
+  }
+
+  return { status: 'ok', tablesRefreshed: count };
+}
+
+// ── Trigger Management ──────────────────
+
+function ddlSetupCacheTrigger(params: { intervalHours?: number }): any {
+  const hours = params?.intervalHours || 1;
+
+  // Remove existing trigger if any
+  const triggers = ScriptApp.getProjectTriggers();
+  for (const trigger of triggers) {
+    if (trigger.getHandlerFunction() === 'ddlRefreshCacheTrigger') {
+      ScriptApp.deleteTrigger(trigger);
+    }
+  }
+
+  // Create new time-based trigger
+  ScriptApp.newTrigger('ddlRefreshCacheTrigger')
+    .timeBased()
+    .everyHours(hours)
+    .create();
+
+  return { status: 'ok', intervalHours: hours, message: `Trigger set to refresh cache every ${hours}h` };
+}
+
+function ddlRemoveCacheTrigger(): any {
+  const triggers = ScriptApp.getProjectTriggers();
+  let removed = 0;
+  for (const trigger of triggers) {
+    if (trigger.getHandlerFunction() === 'ddlRefreshCacheTrigger') {
+      ScriptApp.deleteTrigger(trigger);
+      removed++;
+    }
+  }
+  return { status: 'ok', removed };
+}
+
+// Trigger handler — called by time-based trigger
+function ddlRefreshCacheTrigger(): void {
+  const logger = getLogger();
+  try {
+    const result = ddlRefreshCache();
+    logger.info('ddlRefreshCacheTrigger', 'Cache refreshed', result);
+  } catch (err: any) {
+    logger.warn('ddlRefreshCacheTrigger', 'Cache refresh failed', { error: String(err) });
+  }
+}
+

package/src/templates/.clasp.json.ejs

@@ -0,0 +1 @@
+{"scriptId": "<%- script_id %>", "rootDir": "."<% if (project_id) { %>, "projectId": "<%- project_id %>"<% } %>}

package/src/templates/appsscript.json.ejs

@@ -0,0 +1,16 @@
+{
+  "timeZone": "America/New_York",
+  "dependencies": {},
+  "exceptionLogging": "STACKDRIVER",
+  "runtimeVersion": "V8",
+  "webapp": {
+    "executeAs": "USER_DEPLOYING",
+    "access": "ANYONE_ANONYMOUS"
+  },
+  "oauthScopes": [
+    "https://www.googleapis.com/auth/spreadsheets",
+    "https://www.googleapis.com/auth/drive",
+    "https://www.googleapis.com/auth/script.external_request",
+    "https://www.googleapis.com/auth/script.scriptapp"
+  ]
+}

package/src/templates/config.ts.ejs

@@ -0,0 +1,14 @@
+// Auto-generated by nsa-sheets-db-builder — do not edit manually
+const ENV = '<%- env %>';
+const INSTANCE_TYPE = '<%- instance_type %>';
+const LOGGING_VERBOSITY_LEVEL = <%- logging_verbosity %>;
+
+const DEPLOYER_CONFIG = {
+  name: '<%- config_name %>',
+  env: ENV,
+  instanceType: INSTANCE_TYPE,
+  systemSpreadsheetId: '<%- system_spreadsheet_id %>',
+  driveFolderId: '<%- drive_folder_id %>',
+  loggingVerbosity: LOGGING_VERBOSITY_LEVEL,
+  ddlAdminKey: '<%- ddl_admin_key %>'
+};

package/src/templates/ddl-handler-config.ts.ejs

@@ -0,0 +1,3 @@
+// Auto-generated by nsa-sheets-db-builder — DDL Handler config
+const LOGGING_VERBOSITY_LEVEL = <%- logging_verbosity %>;
+const DDL_ADMIN_KEY = '<%- ddl_admin_key %>';

package/src/templates/ddl-handler-main.ts.ejs

@@ -0,0 +1,56 @@
+// ========================================
+// DDL Handler — Entry Point (POST-only)
+// Auto-generated by nsa-sheets-db-builder
+//
+// Generic, schema-agnostic DDL handler.
+// Deployed once per Google account, shared across all databases.
+// Receives schema/config as parameters (not baked in at build time).
+// ========================================
+
+function getLogger(): any {
+  if (typeof GASLoggerV2 !== 'undefined') {
+    return new GASLoggerV2('ddl-handler', null, LOGGING_VERBOSITY_LEVEL, '');
+  }
+  return {
+    info: (src: string, msg: string, ctx?: any) => console.log(`[INFO] ${src}: ${msg}`),
+    warn: (src: string, msg: string, ctx?: any) => console.warn(`[WARN] ${src}: ${msg}`),
+    error: (err: any) => console.error(`[ERROR]`, err?.message || err),
+    debug: (src: string, msg: string, ctx?: any) => {},
+    getTraceId: () => ''
+  };
+}
+
+function getDDL(): DBDDLV2 {
+  return new DBDDLV2(getLogger());
+}
+
+function jsonResponse(data: any): GoogleAppsScript.Content.TextOutput {
+  return ContentService
+    .createTextOutput(JSON.stringify(data))
+    .setMimeType(ContentService.MimeType.JSON);
+}
+
+function doPost(e: GoogleAppsScript.Events.DoPost): GoogleAppsScript.Content.TextOutput {
+  try {
+    const body = JSON.parse(e?.postData?.contents || '{}');
+
+    // Auth: validate DDL admin key
+    if (!DDL_ADMIN_KEY || body.ddlKey !== DDL_ADMIN_KEY) {
+      return jsonResponse({ error: 'Unauthorized: invalid DDL admin key' });
+    }
+
+    const fnName = body.ddlAction;
+    if (typeof fnName !== 'string' || !fnName.startsWith('ddl')) {
+      return jsonResponse({ error: 'Invalid DDL action' });
+    }
+
+    const fn = (globalThis as any)[fnName];
+    if (typeof fn !== 'function') {
+      return jsonResponse({ error: 'Unknown DDL function: ' + fnName });
+    }
+
+    return jsonResponse(fn(body.params));
+  } catch (err: any) {
+    return jsonResponse({ error: err.message || String(err) });
+  }
+}