nsa-sheets-db-builder 4.0.0

package/libs/triggers.ts

@@ -0,0 +1,113 @@
+/**
+ * System functions and table triggers for sheets-deployer.
+ *
+ * System (always included):
+ *   - refreshTableCache: Mandatory — keeps __sys__tables__ cache warm
+ *
+ * Table triggers (defined per table in tables.json → "triggers"):
+ *   - rebuildSearchIndex: Rebuild full-text search index in system spreadsheet
+ *
+ * Table trigger config example in tables.json:
+ *   "contents": {
+ *     "triggers": [
+ *       { "function": "rebuildSearchIndex", "type": "time", "interval": "hours", "every": 6 }
+ *     ]
+ *   }
+ */
+
+// ── System (mandatory) ──────────────────────
+
+/**
+ * Refresh the __sys__tables__ cache.
+ * Always deployed — keeps table metadata cache warm so reads are fast.
+ * Set up automatically during create; runs on a 1-hour interval.
+ */
+function refreshTableCache(): void {
+  const logger = typeof GASLoggerV2 !== 'undefined'
+    ? new GASLoggerV2(DEPLOYER_CONFIG.name, null, LOGGING_VERBOSITY_LEVEL, '')
+    : { info: () => {}, warn: () => {}, error: () => {}, debug: () => {}, getTraceId: () => '' };
+
+  const tables = typeof DB_SCHEMA !== 'undefined' ? DB_SCHEMA : {};
+  const db = new DBV2({
+    name: DEPLOYER_CONFIG.name,
+    systemSpreadsheetId: DEPLOYER_CONFIG.systemSpreadsheetId,
+    tables,
+    loggingVerbosity: DEPLOYER_CONFIG.loggingVerbosity
+  } as DBConfigV2, logger);
+
+  try {
+    db.refreshCache();
+    logger.info('refreshTableCache', 'Cache refreshed successfully');
+  } catch (err: any) {
+    logger.error(err);
+  }
+}
+
+// ── Table triggers (optional) ───────────────
+
+/**
+ * Rebuild the full-text search index.
+ *
+ * Creates/updates a __search_index__ sheet in the system spreadsheet
+ * with flattened text from all searchable fields across all tables.
+ * Enables fast keyword search without scanning every row.
+ */
+function rebuildSearchIndex(): void {
+  const logger = typeof GASLoggerV2 !== 'undefined'
+    ? new GASLoggerV2(DEPLOYER_CONFIG.name, null, LOGGING_VERBOSITY_LEVEL, '')
+    : { info: () => {}, warn: () => {}, error: () => {}, debug: () => {}, getTraceId: () => '' };
+
+  const tables = typeof DB_SCHEMA !== 'undefined' ? DB_SCHEMA : {};
+  const db = new DBV2({
+    name: DEPLOYER_CONFIG.name,
+    systemSpreadsheetId: DEPLOYER_CONFIG.systemSpreadsheetId,
+    tables,
+    loggingVerbosity: DEPLOYER_CONFIG.loggingVerbosity
+  } as DBConfigV2, logger);
+
+  const indexRows: any[][] = [['entity_type', 'entity_id', 'text']];
+  let totalIndexed = 0;
+
+  for (const [tableName, tableDef] of Object.entries(tables) as any) {
+    try {
+      const table = db.table(tableName);
+      if (!table) continue;
+
+      const schema = tableDef.schema || {};
+      const textFields = Object.keys(schema).filter(f =>
+        schema[f].type === 'string' && !f.startsWith('__')
+      );
+
+      if (textFields.length === 0) continue;
+
+      const result = table.list({ filters: { __archived__: false } });
+      const rows = result?.data || [];
+
+      for (const row of rows) {
+        const textParts = textFields.map(f => row[f] || '').filter(Boolean);
+        if (textParts.length > 0) {
+          indexRows.push([tableName, row.id, textParts.join(' ')]);
+          totalIndexed++;
+        }
+      }
+    } catch (err: any) {
+      logger.warn('rebuildSearchIndex', `Error indexing ${tableName}`, { error: String(err) });
+    }
+  }
+
+  try {
+    const ss = SpreadsheetApp.openById(DEPLOYER_CONFIG.systemSpreadsheetId);
+    let sheet = ss.getSheetByName('__search_index__');
+    if (!sheet) {
+      sheet = ss.insertSheet('__search_index__');
+    }
+    sheet.clearContents();
+    if (indexRows.length > 0) {
+      sheet.getRange(1, 1, indexRows.length, 3).setValues(indexRows);
+    }
+  } catch (err: any) {
+    logger.warn('rebuildSearchIndex', 'Failed to write search index', { error: String(err) });
+  }
+
+  logger.info('rebuildSearchIndex', `Indexed ${totalIndexed} record(s) from ${Object.keys(tables).length} table(s)`);
+}

package/package.json

@@ -0,0 +1,73 @@
+{
+  "name": "nsa-sheets-db-builder",
+  "version": "4.0.0",
+  "description": "DDL provisioner for Google Sheets — creates spreadsheets, sheets, and headers",
+  "type": "module",
+  "license": "MIT",
+  "author": "NoStackApps",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/nostackapps/gas-tools.git",
+    "directory": "sheets-deployer"
+  },
+  "homepage": "https://github.com/nostackapps/gas-tools/tree/main/sheets-deployer#readme",
+  "bugs": {
+    "url": "https://github.com/nostackapps/gas-tools/issues"
+  },
+  "keywords": [
+    "google-sheets",
+    "google-apps-script",
+    "clasp",
+    "ddl",
+    "database",
+    "spreadsheet",
+    "provisioner",
+    "schema",
+    "cli"
+  ],
+  "bin": {
+    "nsa-sheets-db-builder": "./bin/sheets-deployer.mjs"
+  },
+  "files": [
+    "bin/",
+    "scripts/",
+    "src/",
+    "templates/",
+    "libs/",
+    "LICENSE",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=22.0.0"
+  },
+  "scripts": {
+    "init": "node scripts/init.mjs",
+    "build": "node scripts/build.mjs",
+    "clean": "node scripts/clean.mjs",
+    "push": "node scripts/build.mjs --push",
+    "deploy": "node scripts/build.mjs --push --deploy",
+    "create": "node scripts/create.mjs",
+    "provision": "node scripts/provision.mjs",
+    "show": "node scripts/show.mjs",
+    "describe": "node scripts/describe.mjs",
+    "drop": "node scripts/drop.mjs",
+    "sync": "node scripts/sync.mjs",
+    "status": "node scripts/show.mjs --status",
+    "set-key": "node scripts/set-key.mjs",
+    "rotate-key": "node scripts/set-key.mjs --rotate",
+    "refresh-cache": "node scripts/refresh-cache.mjs",
+    "setup-trigger": "node scripts/setup-trigger.mjs",
+    "remove-trigger": "node scripts/setup-trigger.mjs --remove",
+    "login": "node scripts/login.mjs",
+    "whoami": "node scripts/whoami.mjs",
+    "setup": "node scripts/setup.mjs",
+    "ddl-handler": "node scripts/ddl-handler.mjs"
+  },
+  "dependencies": {
+    "ejs": "^3.1.10",
+    "esbuild": "^0.27.3"
+  },
+  "peerDependencies": {
+    "@google/clasp": ">=3.0.0"
+  }
+}

package/scripts/build.mjs

@@ -0,0 +1,513 @@
+#!/usr/bin/env node
+
+/**
+ * Build pipeline for nsa-sheets-db-builder (instance-aware)
+ *
+ * Usage:
+ *   node scripts/build.mjs --db <name> [--env <env>] [--instance <type>] [--push] [--deploy]
+ *
+ * Without --instance: builds all instances for the environment.
+ * With --instance: builds only that instance.
+ * --push and --deploy require --instance (can't push all at once).
+ *
+ * Pipeline (per instance):
+ *   1. Load project.json + api.json
+ *   2. Clean/recreate dist/<name>/<instance>/
+ *   3. Process library files from dbs/<name>/libs/ → strip imports/exports → .js
+ *   4. Render config template (099) → .js (with instance_type)
+ *   5. Generate schema from tables.json (100) → .js
+ *   6. Process source files — ddl.ts (101), main.ts.ejs (102) → .js
+ *   7. Render .clasp.json + appsscript.json templates
+ *   8. Optional: clasp push / clasp deploy (requires --instance)
+ */
+
+import fs from 'fs';
+import path from 'path';
+import { execSync } from 'child_process';
+import ejs from 'ejs';
+import { transformSync } from 'esbuild';
+import {
+  parseArgs, requireDb, loadDbConfig, getEnvConfig,
+  getDistDirForInstance, getDistDir, getTablesPath, getLibsDir,
+  getAllInstances, requireInstance, loadTables,
+  loadRbacConfig, loadViewsConfig, loadCustomMethodsConfig, getFeatures, validateRbacRequirements,
+  getDdlHandlerDistDir, getRootEnvConfig,
+  PACKAGE_ROOT, COMMON_LIBS_DIR, DBS_DIR, ensureAuthenticated
+} from './lib/utils.mjs';
+
+// ────────────────────────────────────────
+// Instance type → short suffix for deployment names
+// ────────────────────────────────────────
+
+/** Build the --user flag string (empty when using default credentials). */
+function claspUserFlag(profile) {
+  return profile ? ` --user ${profile}` : '';
+}
+
+const TYPE_SUFFIX = {
+  'read-write': '[RW]',
+  'read-only':  '[R]',
+  'write-only': '[W]'
+};
+
+export function getDeploymentDescription(dbName, instanceType, env) {
+  const suffix = TYPE_SUFFIX[instanceType] || `[${instanceType}]`;
+  return `${dbName} ${env} ${suffix}`;
+}
+
+// ────────────────────────────────────────
+// Strip imports/exports for GAS compatibility
+// ────────────────────────────────────────
+
+function stripImportsExports(content) {
+  const lines = content.split('\n');
+  const result = [];
+
+  for (let line of lines) {
+    if (/^\s*import\s+/.test(line)) continue;
+    if (/^\s*export\s*\{/.test(line)) continue;
+
+    if (/^\s*export\s+(const|let|var|function|class|interface|type|enum)/.test(line)) {
+      line = line.replace(/^\s*export\s+/, '');
+    }
+
+    if (/^\s*export\s+default\s+/.test(line)) {
+      line = line.replace(/^\s*export\s+default\s+/, '');
+    }
+
+    result.push(line);
+  }
+
+  return result.join('\n');
+}
+
+/**
+ * Strip TypeScript type annotations using esbuild.
+ */
+function stripTypeAnnotations(content) {
+  const result = transformSync(content, {
+    loader: 'ts',
+    target: 'es2020',
+    minify: false,
+    sourcemap: false,
+  });
+  return result.code;
+}
+
+// ────────────────────────────────────────
+// Build a single instance
+// ────────────────────────────────────────
+
+export function buildInstance(dbName, config, env, envConfig, instance, features, rbacConfig, viewsConfig, customMethodsConfig) {
+  const { scriptId, type: instanceType } = instance;
+  const distDir = getDistDirForInstance(dbName, instanceType);
+
+  console.log(`\n  Building instance: ${instanceType} (${scriptId.slice(0, 16)}...)`);
+
+  // Clean and recreate
+  if (fs.existsSync(distDir)) {
+    fs.rmSync(distDir, { recursive: true });
+  }
+  fs.mkdirSync(distDir, { recursive: true });
+
+  const templateDir = path.join(PACKAGE_ROOT, 'src', 'templates');
+  const dbDir = path.join(DBS_DIR, dbName);
+
+  // 1. Libraries from project's libs/ directory (sorted alphabetically = numeric order)
+  const libsDir = getLibsDir(dbName);
+  let fileIndex = 0;
+
+  if (fs.existsSync(libsDir)) {
+    const libFiles = fs.readdirSync(libsDir)
+      .filter(f => f.endsWith('.ts') || f.endsWith('.js'))
+      .sort();
+
+    for (const libFile of libFiles) {
+      const content = fs.readFileSync(path.join(libsDir, libFile), 'utf8');
+      let processed = stripImportsExports(content);
+      if (libFile.endsWith('.ts')) {
+        processed = stripTypeAnnotations(processed);
+      }
+      const outName = `${String(fileIndex).padStart(3, '0')}_lib_${path.parse(libFile).name}.js`;
+      fs.writeFileSync(path.join(distDir, outName), processed);
+      console.log(`    ${outName}`);
+      fileIndex++;
+    }
+  }
+
+  // 2. Config (099) — rendered with instance_type
+  const configTemplatePath = path.join(templateDir, 'config.ts.ejs');
+  if (fs.existsSync(configTemplatePath)) {
+    const configTemplate = fs.readFileSync(configTemplatePath, 'utf8');
+    const configContent = ejs.render(configTemplate, {
+      env: env,
+      instance_type: instanceType,
+      logging_verbosity: config.settings?.loggingVerbosity ?? 2,
+      config_name: config.name,
+      system_spreadsheet_id: envConfig.systemSpreadsheetId || '',
+      drive_folder_id: envConfig.driveFolderId || '',
+      ddl_admin_key: envConfig.ddlAdminKey || ''
+    });
+    const configOut = '099_config.js';
+    fs.writeFileSync(path.join(distDir, configOut), configContent);
+    console.log(`    ${configOut}`);
+  }
+
+  // 3. Schema (100) — generated from tables.json
+  const tablesPath = getTablesPath(dbName);
+  if (fs.existsSync(tablesPath)) {
+    const tablesJson = fs.readFileSync(tablesPath, 'utf8');
+    const schemaJs = `var DB_SCHEMA = ${tablesJson.trim()};\n`;
+    const schemaOut = '100_schema.js';
+    fs.writeFileSync(path.join(distDir, schemaOut), schemaJs);
+    console.log(`    ${schemaOut}`);
+  } else {
+    console.error(`ERROR: tables.json not found at ${tablesPath}`);
+    process.exit(1);
+  }
+
+  // 4. DDL (101) — static source file
+  const ddlPath = path.join(PACKAGE_ROOT, 'src', 'api', 'ddl.ts');
+  if (fs.existsSync(ddlPath)) {
+    const content = fs.readFileSync(ddlPath, 'utf8');
+    let processed = stripImportsExports(content);
+    processed = stripTypeAnnotations(processed);
+    const outName = '101_api_ddl.js';
+    fs.writeFileSync(path.join(distDir, outName), processed);
+    console.log(`    ${outName}`);
+  }
+
+  // 5. RBAC middleware (102) — conditional
+  if (features.rbac.enabled && rbacConfig) {
+    const rbacTemplatePath = path.join(templateDir, 'rbac.ts.ejs');
+    if (fs.existsSync(rbacTemplatePath)) {
+      const rbacTemplate = fs.readFileSync(rbacTemplatePath, 'utf8');
+      let rbacContent = ejs.render(rbacTemplate, {
+        auth_mode: features.authMode,
+        rbac_config: rbacConfig
+      });
+      rbacContent = stripTypeAnnotations(rbacContent);
+      const rbacOut = '102_rbac.js';
+      fs.writeFileSync(path.join(distDir, rbacOut), rbacContent);
+      console.log(`    ${rbacOut} (RBAC: ${features.authMode} auth)`);
+    }
+  }
+
+  // 6. Views runtime (103) + alasql (104) — conditional
+  const viewNames = viewsConfig ? Object.keys(viewsConfig) : [];
+  if (features.views.enabled && viewsConfig && viewNames.length > 0) {
+    const viewsTemplatePath = path.join(templateDir, 'views.ts.ejs');
+    if (fs.existsSync(viewsTemplatePath)) {
+      const viewsTemplate = fs.readFileSync(viewsTemplatePath, 'utf8');
+      let viewsContent = ejs.render(viewsTemplate, { views_config: viewsConfig });
+      viewsContent = stripTypeAnnotations(viewsContent);
+      const viewsOut = '103_views.js';
+      fs.writeFileSync(path.join(distDir, viewsOut), viewsContent);
+      console.log(`    ${viewsOut} (${viewNames.length} view(s))`);
+    }
+
+    // alasql — should already be in project libs (scaffolded during init)
+    // If not in project libs, fall back to package libs/
+    const projectAlasql = fs.readdirSync(distDir).find(f => f.includes('alasql'));
+    if (!projectAlasql) {
+      const alasqlPath = path.join(PACKAGE_ROOT, 'libs', 'alasql.js');
+      if (fs.existsSync(alasqlPath)) {
+        const alasqlOut = '104_alasql.js';
+        fs.copyFileSync(alasqlPath, path.join(distDir, alasqlOut));
+        console.log(`    ${alasqlOut} (alasql runtime — fallback from package)`);
+      } else {
+        console.error('    ERROR: alasql not found — views require the alasql GAS fork');
+        process.exit(1);
+      }
+    }
+  }
+
+  // 7. Custom method handlers — declared in customMethods.json, files in overrides/
+  const overridesDir = path.join(dbDir, 'overrides');
+  const customMethods = [];
+  const declaredMethods = customMethodsConfig || {};
+
+  let methodIdx = 105;
+  for (const [actionName, methodDef] of Object.entries(declaredMethods).sort(([a], [b]) => a.localeCompare(b))) {
+    // Resolve handler file: explicit path or convention overrides/<action>.ts
+    const handler = methodDef.handler || `${actionName}.ts`;
+    const handlerPath = path.isAbsolute(handler)
+      ? handler
+      : path.join(overridesDir, handler);
+
+    if (!fs.existsSync(handlerPath)) {
+      console.warn(`    Warning: custom method "${actionName}" handler not found: ${handlerPath}`);
+      continue;
+    }
+
+    const content = fs.readFileSync(handlerPath, 'utf8');
+    let processed = stripImportsExports(content);
+    if (handlerPath.endsWith('.ts')) {
+      processed = stripTypeAnnotations(processed);
+    }
+
+    customMethods.push(actionName);
+
+    const outName = `${String(methodIdx).padStart(3, '0')}_method_${actionName}.js`;
+    fs.writeFileSync(path.join(distDir, outName), processed);
+    console.log(`    ${outName} (custom method: ${actionName})`);
+    methodIdx++;
+  }
+
+  // 8. Main (110) — rendered from EJS template with all feature flags + methods
+  const mainTemplatePath = path.join(templateDir, 'main.ts.ejs');
+  if (fs.existsSync(mainTemplatePath)) {
+    const mainTemplate = fs.readFileSync(mainTemplatePath, 'utf8');
+    let mainContent = ejs.render(mainTemplate, {
+      instance_type: instanceType,
+      auth_mode: features.authMode,
+      rbac_enabled: features.rbac.enabled && !!rbacConfig,
+      views_enabled: features.views.enabled && viewNames.length > 0,
+      view_names: viewNames,
+      custom_methods: customMethods
+    });
+    mainContent = stripTypeAnnotations(mainContent);
+    const mainOut = '110_api_main.js';
+    fs.writeFileSync(path.join(distDir, mainOut), mainContent);
+    console.log(`    ${mainOut}`);
+  }
+
+  // 9. Manifests
+  const claspTemplate = fs.readFileSync(path.join(templateDir, '.clasp.json.ejs'), 'utf8');
+  const claspContent = ejs.render(claspTemplate, { script_id: scriptId, project_id: envConfig.projectId || getRootEnvConfig(env).projectId || '' });
+  fs.writeFileSync(path.join(distDir, '.clasp.json'), claspContent);
+  console.log('    .clasp.json');
+
+  const appsscriptTemplate = fs.readFileSync(path.join(templateDir, 'appsscript.json.ejs'), 'utf8');
+  const appsscriptContent = ejs.render(appsscriptTemplate, {});
+  fs.writeFileSync(path.join(distDir, 'appsscript.json'), appsscriptContent);
+  console.log('    appsscript.json');
+
+  const fileCount = fs.readdirSync(distDir).length;
+  console.log(`    → ${fileCount} files`);
+
+  return distDir;
+}
+
+// ────────────────────────────────────────
+// Build DDL Handler (per-account, shared)
+// ────────────────────────────────────────
+
+/**
+ * Build the DDL handler project — a lightweight, schema-agnostic web app.
+ *
+ * Output (dist/__ddl-handler__/):
+ *   000_lib_gaserror.js     ← from common/libs/gaserror.ts
+ *   001_lib_gaslogger.js    ← from common/libs/gaslogger.ts
+ *   002_lib_db_ddl.js       ← from libs/db_ddl.ts
+ *   099_config.js           ← ddl-handler-config.ts.ejs
+ *   101_api_ddl.js          ← ddl-handler-entry.ts (generic funcs only)
+ *   110_ddl_main.js         ← ddl-handler-main.ts.ejs
+ *   .clasp.json
+ *   appsscript.json
+ *
+ * @param {string} ddlAdminKey - Admin key for DDL handler authentication
+ * @param {number} loggingVerbosity - Logging verbosity level (default 2)
+ * @param {string} [scriptId] - Script ID for .clasp.json (optional, set later if creating)
+ * @param {string} [projectId] - GCP project ID (optional)
+ * @returns {string} Path to the dist directory
+ */
+export function buildDdlHandler(ddlAdminKey, loggingVerbosity = 2, scriptId = '', projectId = '') {
+  const distDir = getDdlHandlerDistDir();
+
+  console.log(`\n  Building DDL handler → dist/__ddl-handler__/`);
+
+  // Clean and recreate
+  if (fs.existsSync(distDir)) {
+    fs.rmSync(distDir, { recursive: true });
+  }
+  fs.mkdirSync(distDir, { recursive: true });
+
+  const templateDir = path.join(PACKAGE_ROOT, 'src', 'templates');
+
+  // 1. Bundle libs: gaserror.ts → gaslogger.ts → db_ddl.ts
+  const libSources = [
+    { src: path.join(COMMON_LIBS_DIR, 'gaserror.ts'), out: '000_lib_gaserror.js' },
+    { src: path.join(COMMON_LIBS_DIR, 'gaslogger.ts'), out: '001_lib_gaslogger.js' },
+    { src: path.join(PACKAGE_ROOT, 'libs', 'db_ddl.ts'), out: '002_lib_db_ddl.js' }
+  ];
+
+  for (const { src, out } of libSources) {
+    if (!fs.existsSync(src)) {
+      console.error(`  ERROR: library not found: ${src}`);
+      process.exit(1);
+    }
+    const content = fs.readFileSync(src, 'utf8');
+    let processed = stripImportsExports(content);
+    processed = stripTypeAnnotations(processed);
+    fs.writeFileSync(path.join(distDir, out), processed);
+    console.log(`    ${out}`);
+  }
+
+  // 2. Render config: ddl-handler-config.ts.ejs → 099_config.js
+  const configTemplatePath = path.join(templateDir, 'ddl-handler-config.ts.ejs');
+  const configTemplate = fs.readFileSync(configTemplatePath, 'utf8');
+  const configContent = ejs.render(configTemplate, {
+    ddl_admin_key: ddlAdminKey,
+    logging_verbosity: loggingVerbosity
+  });
+  fs.writeFileSync(path.join(distDir, '099_config.js'), configContent);
+  console.log('    099_config.js');
+
+  // 3. Process DDL entry points: ddl-handler-entry.ts → 101_api_ddl.js
+  const ddlEntryPath = path.join(PACKAGE_ROOT, 'src', 'api', 'ddl-handler-entry.ts');
+  if (!fs.existsSync(ddlEntryPath)) {
+    console.error(`  ERROR: DDL handler entry not found: ${ddlEntryPath}`);
+    process.exit(1);
+  }
+  let ddlContent = fs.readFileSync(ddlEntryPath, 'utf8');
+  ddlContent = stripImportsExports(ddlContent);
+  ddlContent = stripTypeAnnotations(ddlContent);
+  fs.writeFileSync(path.join(distDir, '101_api_ddl.js'), ddlContent);
+  console.log('    101_api_ddl.js');
+
+  // 4. Render main: ddl-handler-main.ts.ejs → 110_ddl_main.js
+  const mainTemplatePath = path.join(templateDir, 'ddl-handler-main.ts.ejs');
+  const mainTemplate = fs.readFileSync(mainTemplatePath, 'utf8');
+  let mainContent = ejs.render(mainTemplate, {});
+  mainContent = stripTypeAnnotations(mainContent);
+  fs.writeFileSync(path.join(distDir, '110_ddl_main.js'), mainContent);
+  console.log('    110_ddl_main.js');
+
+  // 5. Render manifests
+  if (scriptId) {
+    const claspTemplate = fs.readFileSync(path.join(templateDir, '.clasp.json.ejs'), 'utf8');
+    const claspContent = ejs.render(claspTemplate, { script_id: scriptId, project_id: projectId || '' });
+    fs.writeFileSync(path.join(distDir, '.clasp.json'), claspContent);
+    console.log('    .clasp.json');
+  }
+
+  const appsscriptTemplate = fs.readFileSync(path.join(templateDir, 'appsscript.json.ejs'), 'utf8');
+  const appsscriptContent = ejs.render(appsscriptTemplate, {});
+  fs.writeFileSync(path.join(distDir, 'appsscript.json'), appsscriptContent);
+  console.log('    appsscript.json');
+
+  const fileCount = fs.readdirSync(distDir).length;
+  console.log(`    → ${fileCount} files`);
+
+  return distDir;
+}
+
+// ────────────────────────────────────────
+// Main
+// ────────────────────────────────────────
+
+async function build() {
+  const args = parseArgs();
+  const dbName = requireDb(args, 'build.mjs');
+
+  const config = loadDbConfig(dbName);
+  const { env, envConfig } = getEnvConfig(config, args.env);
+  const features = getFeatures(config);
+
+  console.log(`Building ${dbName} for environment: ${env}`);
+
+  // Load optional feature configs
+  let rbacConfig = null;
+  let viewsConfig = null;
+  const customMethodsConfig = loadCustomMethodsConfig(dbName);
+  const methodCount = Object.keys(customMethodsConfig).length;
+  if (methodCount > 0) {
+    console.log(`  Custom methods: ${methodCount} declared`);
+  }
+
+  if (features.rbac.enabled) {
+    rbacConfig = loadRbacConfig(dbName);
+    if (!rbacConfig) {
+      console.error('RBAC enabled in project.json but rbac.json not found.');
+      process.exit(1);
+    }
+    const tables = loadTables(dbName);
+    const errors = validateRbacRequirements(tables, rbacConfig);
+    if (errors.length > 0) {
+      console.error('RBAC validation failed:');
+      for (const err of errors) console.error(`  - ${err}`);
+      process.exit(1);
+    }
+    console.log(`  RBAC: enabled (${features.authMode} auth, ${Object.keys(rbacConfig.roles).length} role(s))`);
+  }
+
+  if (features.views.enabled) {
+    viewsConfig = loadViewsConfig(dbName);
+    if (!viewsConfig) {
+      console.error('Views enabled in project.json but views.json not found.');
+      process.exit(1);
+    }
+    console.log(`  Views: enabled (${Object.keys(viewsConfig).length} view(s))`);
+  }
+
+  // Determine which instances to build
+  const instances = args.instance
+    ? [requireInstance(args, envConfig)]
+    : getAllInstances(envConfig);
+
+  if (instances.length === 0) {
+    console.error('No instances configured. Run init with --instances to set up instances.');
+    process.exit(1);
+  }
+
+  // Clean top-level dist/<db>/ first (remove stale instance dirs)
+  const topDistDir = getDistDir(dbName);
+  if (fs.existsSync(topDistDir)) {
+    fs.rmSync(topDistDir, { recursive: true });
+  }
+
+  // Build each instance
+  for (const inst of instances) {
+    buildInstance(dbName, config, env, envConfig, inst, features, rbacConfig, viewsConfig, customMethodsConfig);
+  }
+
+  console.log(`\nBuild complete → dist/${dbName}/`);
+
+  // Push/deploy require --instance
+  if (args.push || args.deploy) {
+    if (!args.instance && instances.length > 1) {
+      console.error('\n--push and --deploy require --instance when multiple instances exist.');
+      process.exit(1);
+    }
+
+    const inst = requireInstance(args, envConfig);
+    const distDir = getDistDirForInstance(dbName, inst.type);
+    const userProfile = await ensureAuthenticated(dbName, args, envConfig, env);
+
+    if (args.push || args.deploy) {
+      console.log(`\nPushing ${inst.type} to Google Apps Script...`);
+      try {
+        execSync(`npx --prefer-offline @google/clasp push${claspUserFlag(userProfile)}`, { cwd: distDir, stdio: 'inherit' });
+        console.log('Push complete.');
+      } catch {
+        console.error('clasp push failed.');
+        process.exit(1);
+      }
+    }
+
+    if (args.deploy) {
+      const desc = getDeploymentDescription(dbName, inst.type, env);
+      console.log(`\nDeploying ${inst.type} as "${desc}"...`);
+      try {
+        if (inst.deploymentId) {
+          execSync(`npx --prefer-offline @google/clasp update-deployment ${inst.deploymentId} --description '${desc}'${claspUserFlag(userProfile)}`, { cwd: distDir, stdio: 'inherit' });
+          console.log(`Deployment updated: ${inst.deploymentId}`);
+        } else {
+          execSync(`npx --prefer-offline @google/clasp deploy --description '${desc}'${claspUserFlag(userProfile)}`, { cwd: distDir, stdio: 'inherit' });
+          console.log('New deployment created.');
+        }
+      } catch {
+        console.error('clasp deploy failed.');
+        process.exit(1);
+      }
+    }
+  }
+}
+
+// Only run when executed directly (not when imported)
+import { fileURLToPath } from 'url';
+const __build_filename = fileURLToPath(import.meta.url);
+if (process.argv[1] === __build_filename) {
+  build();
+}