nsa-sheets-db-builder 4.0.0

package/scripts/clean.mjs

@@ -0,0 +1,31 @@
+#!/usr/bin/env node
+
+/**
+ * Clean built output for nsa-sheets-db-builder.
+ *
+ * Usage:
+ *   node scripts/clean.mjs --db <name>   # Clean dist/<name>/
+ *   node scripts/clean.mjs               # Clean all of dist/
+ */
+
+import fs from 'fs';
+import { parseArgs, getDistDir, DIST_DIR } from './lib/utils.mjs';
+
+const args = parseArgs();
+
+if (args.db) {
+  const distDir = getDistDir(args.db);
+  if (fs.existsSync(distDir)) {
+    fs.rmSync(distDir, { recursive: true });
+    console.log(`Cleaned dist/${args.db}/`);
+  } else {
+    console.log(`dist/${args.db}/ does not exist, nothing to clean.`);
+  }
+} else {
+  if (fs.existsSync(DIST_DIR)) {
+    fs.rmSync(DIST_DIR, { recursive: true });
+    console.log('Cleaned dist/ (all DBs)');
+  } else {
+    console.log('dist/ does not exist, nothing to clean.');
+  }
+}

package/scripts/create.mjs

@@ -0,0 +1,94 @@
+#!/usr/bin/env node
+
+/**
+ * Set up a new DB project: Drive folder + system spreadsheet + data spreadsheet + trigger.
+ * After creation, updates tables.json to replace __new__ spreadsheetIds with real IDs.
+ *
+ * Usage:
+ *   node scripts/create.mjs --db <name> [--env <env>] [--instance <type>]
+ */
+
+import { parseArgs, requireDb, loadDbConfig, getEnvConfig, getDistDirForInstance, claspRun, loadTables, saveTables, saveProjectConfig, requireInstance, ensureAuthenticated } from './lib/utils.mjs';
+
+const args = parseArgs();
+const dbName = requireDb(args, 'create.mjs');
+const config = loadDbConfig(dbName);
+const { env, envConfig } = getEnvConfig(config, args.env);
+const instance = requireInstance(args, envConfig);
+const distDir = getDistDirForInstance(dbName, instance.type);
+
+if (envConfig.systemSpreadsheetId) {
+  console.log(`Environment "${env}" already set up:`);
+  console.log(`  systemSpreadsheetId: ${envConfig.systemSpreadsheetId}`);
+  console.log(`  driveFolderId: ${envConfig.driveFolderId}`);
+  console.log('\nTo recreate, clear systemSpreadsheetId in project.json first.');
+  process.exit(0);
+}
+
+// Auth enforcement
+const userProfile = await ensureAuthenticated(dbName, args, envConfig, env);
+
+// 1. Setup: create Drive folder + system spreadsheet + trigger
+const folderName = `${config.name}-${env}`;
+console.log(`Setting up ${dbName} (${env})...`);
+console.log(`  Creating Drive folder: ${folderName}`);
+
+const setupResult = claspRun(distDir, 'ddlSetup', [{
+  name: folderName,
+  driveFolderId: envConfig.driveFolderId || undefined
+}], { userProfile });
+
+if (!setupResult?.systemSpreadsheetId) {
+  console.error('\nSetup failed:', JSON.stringify(setupResult, null, 2));
+  process.exit(1);
+}
+
+envConfig.driveFolderId = setupResult.folderId;
+envConfig.systemSpreadsheetId = setupResult.systemSpreadsheetId;
+
+console.log(`  Drive folder: ${setupResult.folderUrl}`);
+console.log(`  System spreadsheet: ${setupResult.systemSpreadsheetId}`);
+
+// 2. Check tables.json for __new__ spreadsheetIds and create data spreadsheets
+const tables = loadTables(dbName);
+let createdCount = 0;
+
+// Find tables that need a new spreadsheet
+const needsNew = Object.entries(tables).filter(([, t]) => t.spreadsheetId === '__new__');
+
+if (needsNew.length > 0) {
+  const dataName = `${config.name}-data`;
+  console.log(`  Creating data spreadsheet: ${dataName}`);
+
+  const dataResult = claspRun(distDir, 'ddlCreateDataSpreadsheet', [{
+    name: dataName,
+    folderId: setupResult.folderId
+  }], { userProfile });
+
+  if (dataResult?.spreadsheetId) {
+    console.log(`  Data spreadsheet: ${dataResult.spreadsheetId}`);
+
+    // Replace __new__ with real spreadsheet ID in tables.json
+    for (const [name, table] of Object.entries(tables)) {
+      if (table.spreadsheetId === '__new__') {
+        table.spreadsheetId = dataResult.spreadsheetId;
+      }
+    }
+    saveTables(dbName, tables);
+    createdCount++;
+
+    console.log(`  Updated tables.json: replaced __new__ → ${dataResult.spreadsheetId}`);
+  } else {
+    console.warn('  Warning: data spreadsheet creation result:', JSON.stringify(dataResult, null, 2));
+  }
+}
+
+// 3. Save project config
+saveProjectConfig(dbName, config);
+
+console.log(`\nSetup complete for ${dbName} (${env}).`);
+console.log(`  Written to dbs/${dbName}/project.json`);
+if (createdCount > 0) {
+  console.log(`  Updated dbs/${dbName}/tables.json with spreadsheet IDs`);
+}
+console.log(`\nNext: nsa-sheets-db-builder provision --db ${dbName}`);

package/scripts/ddl-handler.mjs

@@ -0,0 +1,232 @@
+#!/usr/bin/env node
+
+/**
+ * Standalone DDL handler management.
+ *
+ * The DDL handler is a separate, generic Apps Script project deployed
+ * once per Google account. It handles schema operations (create folders,
+ * spreadsheets, provision tables, etc.) via HTTP POST.
+ *
+ * This script can be used independently of setup.mjs to:
+ *   - Build the DDL handler
+ *   - Push it to Apps Script
+ *   - Deploy it as a web app
+ *
+ * The DDL handler reference is stored in .nsaproject.json (root config)
+ * under environments.<env>.ddlHandler.
+ *
+ * Usage:
+ *   node scripts/ddl-handler.mjs [--build] [--push] [--deploy]
+ *     --db <name>          DB project (for auth profile resolution)
+ *     --env <env>          Environment (default: dev)
+ *     --force              Skip account validation
+ *     --inherit            Use default clasp credentials
+ *
+ * Examples:
+ *   # Build + push + deploy (default: does all three):
+ *   nsa-sheets-db-builder ddl-handler --db my-app
+ *
+ *   # Just rebuild (e.g. after updating libs):
+ *   nsa-sheets-db-builder ddl-handler --db my-app --build
+ *
+ *   # Push + update existing deployment:
+ *   nsa-sheets-db-builder ddl-handler --db my-app --push --deploy
+ */
+
+import fs from 'fs';
+import os from 'os';
+import path from 'path';
+import crypto from 'crypto';
+import { execSync } from 'child_process';
+import {
+  parseArgs, requireDb, loadDbConfig, getEnvConfig,
+  ensureAuthenticated, resolveAccount,
+  loadRootConfig, saveRootConfig,
+  getDdlHandlerDistDir
+} from './lib/utils.mjs';
+import { buildDdlHandler } from './build.mjs';
+
+// ────────────────────────────────────────
+// Helpers
+// ────────────────────────────────────────
+
+function parseDeploymentId(output) {
+  const match = output.match(/(?:^Deployed |^- )(\S+) @/m);
+  return match ? match[1] : null;
+}
+
+function userFlag(profile) {
+  return profile ? ` --user ${profile}` : '';
+}
+
+function generateAdminKey() {
+  return crypto.randomBytes(24).toString('hex');
+}
+
+// ────────────────────────────────────────
+// Main
+// ────────────────────────────────────────
+
+async function main() {
+  const args = parseArgs();
+  const dbName = requireDb(args, 'ddl-handler.mjs');
+
+  const config = loadDbConfig(dbName);
+  const { env, envConfig } = getEnvConfig(config, args.env);
+
+  const account = resolveAccount(envConfig, env);
+  if (!account) {
+    console.error('ERROR: account not set.');
+    console.error(`Set "account" in .nsaproject.json → environments.${env}`);
+    process.exit(1);
+  }
+
+  console.log(`\nDDL Handler — account: ${account} (via ${dbName}/${env})`);
+  console.log('='.repeat(50));
+
+  const userProfile = await ensureAuthenticated(dbName, args, envConfig, env);
+
+  // Default: if no flags provided, do all three
+  const doBuild = args.build || (!args.build && !args.push && !args.deploy);
+  const doPush = args.push || (!args.build && !args.push && !args.deploy);
+  const doDeploy = args.deploy || (!args.build && !args.push && !args.deploy);
+
+  // Load existing handler state from root config
+  let rootConfig = loadRootConfig();
+  let rootEnv = rootConfig.environments?.[env] || {};
+  let handler = rootEnv.ddlHandler || {};
+
+  const ddlAdminKey = handler.ddlAdminKey || generateAdminKey();
+  let scriptId = handler.scriptId || '';
+  let deploymentId = handler.deploymentId || '';
+
+  // ── Create GAS project if needed ──
+
+  if (!scriptId) {
+    const title = `ddl-handler-${account.split('@')[0]}`;
+    console.log(`\nCreating GAS project: ${title}`);
+
+    const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'nsa-sheets-db-builder-ddl-'));
+    try {
+      execSync(
+        `npx --prefer-offline @google/clasp create --type webapp --title "${title}" --rootDir .${userFlag(userProfile)}`,
+        { cwd: tmpDir, stdio: 'pipe' }
+      );
+
+      const claspJson = JSON.parse(fs.readFileSync(path.join(tmpDir, '.clasp.json'), 'utf8'));
+      scriptId = claspJson.scriptId;
+
+      if (!scriptId) {
+        console.error('ERROR: clasp create succeeded but no scriptId found.');
+        process.exit(1);
+      }
+
+      console.log(`  scriptId: ${scriptId}`);
+    } catch (err) {
+      const stderr = err.stderr?.toString() || '';
+      const stdout = err.stdout?.toString() || '';
+      console.error('\nclasp create failed for DDL handler:');
+      if (stderr) console.error(stderr);
+      if (stdout) console.error(stdout);
+      process.exit(1);
+    } finally {
+      fs.rmSync(tmpDir, { recursive: true, force: true });
+    }
+  } else {
+    console.log(`\nUsing existing scriptId: ${scriptId}`);
+  }
+
+  // ── Build ──
+
+  if (doBuild) {
+    console.log('\n-- Build --');
+    const loggingVerbosity = config.settings?.loggingVerbosity ?? 2;
+    const projectId = rootEnv.projectId || '';
+    buildDdlHandler(ddlAdminKey, loggingVerbosity, scriptId, projectId);
+  }
+
+  // ── Push ──
+
+  if (doPush) {
+    console.log('\n-- Push --');
+    const ddlDistDir = getDdlHandlerDistDir();
+
+    if (!fs.existsSync(path.join(ddlDistDir, '.clasp.json'))) {
+      console.error('ERROR: DDL handler not built yet. Run with --build first.');
+      process.exit(1);
+    }
+
+    console.log('  Pushing DDL handler...');
+    try {
+      execSync(`npx --prefer-offline @google/clasp push --force${userFlag(userProfile)}`, {
+        cwd: ddlDistDir,
+        stdio: 'inherit'
+      });
+    } catch {
+      console.error('  clasp push failed for DDL handler.');
+      process.exit(1);
+    }
+  }
+
+  // ── Deploy ──
+
+  if (doDeploy) {
+    console.log('\n-- Deploy --');
+    const ddlDistDir = getDdlHandlerDistDir();
+
+    if (deploymentId) {
+      console.log(`  Updating deployment: ${deploymentId}`);
+      execSync(
+        `npx --prefer-offline @google/clasp update-deployment ${deploymentId} --description 'DDL Handler'${userFlag(userProfile)}`,
+        { cwd: ddlDistDir, stdio: 'inherit' }
+      );
+    } else {
+      console.log('  Creating new deployment...');
+      const output = execSync(
+        `npx --prefer-offline @google/clasp deploy --description 'DDL Handler'${userFlag(userProfile)}`,
+        { cwd: ddlDistDir, encoding: 'utf8' }
+      );
+      deploymentId = parseDeploymentId(output);
+      if (!deploymentId) {
+        console.error('  ERROR: could not parse deployment ID from clasp output:');
+        console.error(output);
+        process.exit(1);
+      }
+      console.log(`  deploymentId: ${deploymentId}`);
+    }
+  }
+
+  // ── Save state to .nsaproject.json ──
+
+  rootConfig = loadRootConfig();
+  if (!rootConfig.environments) rootConfig.environments = {};
+  if (!rootConfig.environments[env]) rootConfig.environments[env] = {};
+  rootConfig.environments[env].ddlHandler = {
+    scriptId,
+    deploymentId,
+    ddlAdminKey
+  };
+  saveRootConfig(rootConfig);
+
+  // ── Summary ──
+
+  console.log('\n-- DDL Handler --');
+  console.log(`  Account:       ${account}`);
+  console.log(`  Script:        https://script.google.com/d/${scriptId}/edit`);
+  if (deploymentId) {
+    console.log(`  Web app:       https://script.google.com/macros/s/${deploymentId}/exec`);
+  }
+  console.log(`  Admin key:     ${ddlAdminKey.substring(0, 8)}...`);
+  console.log(`  Saved to:      .nsaproject.json`);
+
+  if (doDeploy && !handler.deploymentId) {
+    console.log(`\n  NOTE: Authorize the DDL handler in the Apps Script editor:`);
+    console.log(`    https://script.google.com/d/${scriptId}/edit`);
+    console.log(`    Open the editor → Run any function → Approve permissions.`);
+    console.log(`    This only needs to be done ONCE per Google account.`);
+  }
+
+  console.log('\nDone.');
+}
+
+main();

package/scripts/describe.mjs

@@ -0,0 +1,38 @@
+#!/usr/bin/env node
+
+/**
+ * Describe a table's columns.
+ *
+ * Usage:
+ *   node scripts/describe.mjs --db <name> --table <table> [--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, 'describe.mjs');
+
+if (!args.table) {
+  console.error('Usage: node scripts/describe.mjs --db <name> --table <table> [--env <env>] [--instance <type>]');
+  process.exit(1);
+}
+
+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(`Describing table "${args.table}" for ${dbName} (${env}, ${instance.type})...`);
+
+const result = claspRun(distDir, 'ddlDescribeTable', [{
+  spreadsheetId,
+  table: args.table
+}], { userProfile });
+
+console.log('\nResult:', JSON.stringify(result, null, 2));

package/scripts/drop.mjs

@@ -0,0 +1,39 @@
+#!/usr/bin/env node
+
+/**
+ * Drop a table from a data spreadsheet.
+ *
+ * Usage:
+ *   node scripts/drop.mjs --db <name> --table <table> [--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, 'drop.mjs');
+
+if (!args.table) {
+  console.error('Usage: node scripts/drop.mjs --db <name> --table <table> [--env <env>] [--instance <type>]');
+  process.exit(1);
+}
+
+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(`Dropping table "${args.table}" from ${dbName} (${env}, ${instance.type})...`);
+console.log(`  Data spreadsheet: ${spreadsheetId}`);
+
+const result = claspRun(distDir, 'ddlDropTable', [{
+  spreadsheetId,
+  table: args.table
+}], { userProfile });
+
+console.log('\nResult:', JSON.stringify(result, null, 2));