nsa-sheets-db-builder 4.0.0

package/scripts/lib/utils.mjs

@@ -0,0 +1,1019 @@
+#!/usr/bin/env node
+
+/**
+ * Shared utilities for nsa-sheets-db-builder CLI scripts.
+ *
+ * Provides: arg parsing, config I/O, env resolution,
+ * clasp run wrapper, schema extraction, auth enforcement,
+ * and .env file loading.
+ */
+
+import fs from 'fs';
+import path from 'path';
+import https from 'https';
+import { execSync, spawnSync } from 'child_process';
+import { fileURLToPath } from 'url';
+
+// ── Paths ────────────────────────────────
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+
+/**
+ * PACKAGE_ROOT: where libs/, src/, templates/ live.
+ * When running locally (npm run): same as PROJECT_ROOT.
+ * When running via npx: npm cache / global install dir.
+ */
+export const PACKAGE_ROOT = path.resolve(__dirname, '..', '..');
+
+/**
+ * PROJECT_ROOT: where dbs/, dist/, .env files live (user's working directory).
+ * When running locally: same as PACKAGE_ROOT.
+ * When running via npx: process.cwd().
+ */
+export const PROJECT_ROOT = process.env.NSA_SHEETS_DB_BUILDER_ROOT || PACKAGE_ROOT;
+
+/**
+ * COMMON_LIBS_DIR: path to common (shared) GAS libraries.
+ * Bundled inside the package at libs/common/.
+ */
+export const COMMON_LIBS_DIR = path.join(PACKAGE_ROOT, 'libs', 'common');
+
+// Keep ROOT as alias for backward compat
+export const ROOT = PACKAGE_ROOT;
+
+export const DBS_DIR = path.join(PROJECT_ROOT, 'dbs');
+export const DIST_DIR = path.join(PROJECT_ROOT, 'dist');
+
+// Root project config — shared across all projects under this installation
+const ROOT_CONFIG_PATH = path.join(PROJECT_ROOT, '.nsaproject.json');
+
+// DDL Handler dist directory
+const DDL_HANDLER_DIST_NAME = '__ddl-handler__';
+
+// ── Arg Parsing ──────────────────────────
+
+/**
+ * Parse CLI args into a flat object.
+ * Supports: --db name, --env dev, --table users, --push, --deploy, --status,
+ *           --inherit, --force, --minimal, --libs a,b,c, --key val, --hours n
+ */
+export function parseArgs(argv = process.argv.slice(2)) {
+  const args = {};
+  for (let i = 0; i < argv.length; i++) {
+    const arg = argv[i];
+    if (arg.startsWith('--')) {
+      const key = arg.slice(2);
+      const next = argv[i + 1];
+      if (next && !next.startsWith('--')) {
+        args[key] = next;
+        i++;
+      } else {
+        args[key] = true;
+      }
+    }
+  }
+  return args;
+}
+
+/**
+ * Require --db flag or exit with usage message.
+ */
+export function requireDb(args, scriptName) {
+  if (!args.db) {
+    console.error(`Usage: node scripts/${scriptName} --db <name> [--env <env>]`);
+    process.exit(1);
+  }
+  if (!/^[a-z0-9][a-z0-9_-]*$/i.test(args.db)) {
+    console.error(`Invalid DB name: "${args.db}"`);
+    console.error('Must contain only letters, numbers, hyphens, and underscores.');
+    process.exit(1);
+  }
+  return args.db;
+}
+
+// ── Config I/O ───────────────────────────
+//
+// Project layout:
+//   dbs/<name>/project.json   — name, settings, features, environments (all-in-one)
+//   dbs/<name>/tables.json    — table definitions (schema)
+//   dbs/<name>/rbac.json             — RBAC capabilities + privacy filters (if enabled)
+//   dbs/<name>/views.json            — SQL view definitions (if enabled)
+//   dbs/<name>/customMethods.json    — custom method declarations
+//   dbs/<name>/libs/                 — scaffolded library source files
+//   dbs/<name>/overrides/            — custom method handler files
+
+export function getProjectConfigPath(dbName) {
+  return path.join(DBS_DIR, dbName, 'project.json');
+}
+
+export function getTablesPath(dbName) {
+  return path.join(DBS_DIR, dbName, 'tables.json');
+}
+
+export function getLibsDir(dbName) {
+  return path.join(DBS_DIR, dbName, 'libs');
+}
+
+export function getOverridesDir(dbName) {
+  return path.join(DBS_DIR, dbName, 'overrides');
+}
+
+export function getRbacConfigPath(dbName) {
+  return path.join(DBS_DIR, dbName, 'rbac.json');
+}
+
+export function getViewsConfigPath(dbName) {
+  return path.join(DBS_DIR, dbName, 'views.json');
+}
+
+export function getCustomMethodsConfigPath(dbName) {
+  return path.join(DBS_DIR, dbName, 'customMethods.json');
+}
+
+/**
+ * Load project.json — exits if not found.
+ * This is the single source of truth: name, settings, features, environments.
+ */
+export function loadProjectConfig(dbName) {
+  const p = getProjectConfigPath(dbName);
+  if (!fs.existsSync(p)) {
+    console.error(`project.json not found: ${p}`);
+    process.exit(1);
+  }
+  return JSON.parse(fs.readFileSync(p, 'utf8'));
+}
+
+/**
+ * Alias for loadProjectConfig — all config lives in project.json.
+ */
+export function loadDbConfig(dbName) {
+  return loadProjectConfig(dbName);
+}
+
+/**
+ * Save project.json (all config: name, settings, features, environments).
+ */
+export function saveProjectConfig(dbName, config) {
+  const p = getProjectConfigPath(dbName);
+  fs.writeFileSync(p, JSON.stringify(config, null, 2) + '\n');
+}
+
+/**
+ * Load tables.json — exits if not found.
+ */
+export function loadTables(dbName) {
+  const p = getTablesPath(dbName);
+  if (!fs.existsSync(p)) {
+    console.error(`tables.json not found: ${p}`);
+    process.exit(1);
+  }
+  return JSON.parse(fs.readFileSync(p, 'utf8'));
+}
+
+/**
+ * Save tables.json.
+ */
+export function saveTables(dbName, tables) {
+  const p = getTablesPath(dbName);
+  fs.writeFileSync(p, JSON.stringify(tables, null, 2) + '\n');
+}
+
+/**
+ * Load rbac.json — returns null if not found (feature may be disabled).
+ */
+export function loadRbacConfig(dbName) {
+  const p = getRbacConfigPath(dbName);
+  if (!fs.existsSync(p)) return null;
+  return JSON.parse(fs.readFileSync(p, 'utf8'));
+}
+
+/**
+ * Save rbac.json.
+ */
+export function saveRbacConfig(dbName, rbacConfig) {
+  const p = getRbacConfigPath(dbName);
+  fs.writeFileSync(p, JSON.stringify(rbacConfig, null, 2) + '\n');
+}
+
+/**
+ * Load views.json — returns null if not found (feature may be disabled).
+ */
+export function loadViewsConfig(dbName) {
+  const p = getViewsConfigPath(dbName);
+  if (!fs.existsSync(p)) return null;
+  return JSON.parse(fs.readFileSync(p, 'utf8'));
+}
+
+/**
+ * Save views.json.
+ */
+export function saveViewsConfig(dbName, viewsConfig) {
+  const p = getViewsConfigPath(dbName);
+  fs.writeFileSync(p, JSON.stringify(viewsConfig, null, 2) + '\n');
+}
+
+/**
+ * Load customMethods.json — returns empty object if not found.
+ */
+export function loadCustomMethodsConfig(dbName) {
+  const p = getCustomMethodsConfigPath(dbName);
+  if (!fs.existsSync(p)) return {};
+  return JSON.parse(fs.readFileSync(p, 'utf8'));
+}
+
+/**
+ * Get project features + auth config from project.json.
+ * Returns { authMode, rbac: { enabled }, views: { enabled } }.
+ */
+export function getFeatures(projectConfig) {
+  const features = projectConfig.features || {};
+  return {
+    authMode: projectConfig.authMode || 'noAuth',
+    rbac: {
+      enabled: !!features.rbac?.enabled
+    },
+    views: {
+      enabled: !!features.views?.enabled
+    }
+  };
+}
+
+/**
+ * Validate RBAC config against tables.json.
+ * Ensures users and roles tables exist when RBAC is enabled.
+ */
+export function validateRbacRequirements(tables, rbacConfig) {
+  const errors = [];
+  if (!tables.users) {
+    errors.push('RBAC requires a "users" table in tables.json');
+  }
+  if (!tables.roles) {
+    errors.push('RBAC requires a "roles" table in tables.json');
+  }
+  if (!rbacConfig.roles || Object.keys(rbacConfig.roles).length === 0) {
+    errors.push('rbac.json must define at least one role');
+  }
+  if (!rbacConfig.defaultRole) {
+    errors.push('rbac.json must define a defaultRole');
+  }
+  return errors;
+}
+
+/**
+ * Resolve environment config — uses --env flag or defaults to 'dev'.
+ * Returns { env, envConfig } where envConfig has instances, account, spreadsheetId.
+ */
+export function getEnvConfig(config, envOverride) {
+  const env = envOverride || 'dev';
+  const envConfig = config.environments?.[env];
+  if (!envConfig) {
+    console.error(`Environment "${env}" not found in config. Available: ${Object.keys(config.environments || {}).join(', ')}`);
+    process.exit(1);
+  }
+  return { env, envConfig };
+}
+
+/**
+ * Get unique data spreadsheet IDs from the schema.
+ * Tables with spreadsheetId "__new__" are excluded (not yet created).
+ *
+ * @param {object} schema - Parsed DB_SCHEMA object
+ * @returns {string[]} Array of unique spreadsheet IDs
+ */
+export function getDataSpreadsheetIds(schema) {
+  const ids = new Set();
+  for (const table of Object.values(schema)) {
+    if (table.spreadsheetId && table.spreadsheetId !== '__new__') {
+      ids.add(table.spreadsheetId);
+    }
+  }
+  return [...ids];
+}
+
+/**
+ * Require at least one data spreadsheet in the schema or exit.
+ */
+export function requireDataSpreadsheet(schema, dbName) {
+  const ids = getDataSpreadsheetIds(schema);
+  if (ids.length === 0) {
+    console.error(`No data spreadsheets set in schema for "${dbName}".`);
+    console.error('Run "nsa-sheets-db-builder create -- --db <name>" first.');
+    process.exit(1);
+  }
+  return ids[0];
+}
+
+// ── Dist Dir ─────────────────────────────
+
+/**
+ * Return the dist directory for a given DB name.
+ */
+export function getDistDir(dbName) {
+  return path.join(DIST_DIR, dbName);
+}
+
+/**
+ * Return the dist directory for a specific instance.
+ * Layout: dist/<db>/<instance-type>/
+ */
+export function getDistDirForInstance(dbName, instanceType) {
+  return path.join(DIST_DIR, dbName, instanceType);
+}
+
+// ── Instance Helpers ─────────────────────
+//
+// Config shape: instances keyed by scriptId, value has type + deploymentId.
+//   "instances": { "SCRIPT_ID": { "type": "read-write", "deploymentId": "" } }
+//
+// --instance flag accepts a short alias (rw, r, w), full type, or scriptId.
+
+/** Short aliases → canonical instance type */
+export const INSTANCE_TYPE_ALIASES = {
+  'rw': 'read-write',
+  'r':  'read-only',
+  'w':  'write-only',
+  'read-write': 'read-write',
+  'read-only':  'read-only',
+  'write-only': 'write-only'
+};
+
+export function resolveInstanceType(input) {
+  const canonical = INSTANCE_TYPE_ALIASES[input];
+  if (!canonical) {
+    console.error(`Invalid instance type: "${input}"`);
+    console.error('Valid types: rw (read-write), r (read-only), w (write-only)');
+    process.exit(1);
+  }
+  return canonical;
+}
+
+/**
+ * Get all instances for an environment config.
+ * Each entry: { scriptId, type, deploymentId }
+ *
+ * @param {object} envConfig - Environment config
+ * @returns {Array<{ scriptId: string, type: string, deploymentId: string }>}
+ */
+export function getAllInstances(envConfig) {
+  if (!envConfig.instances) return [];
+  return Object.entries(envConfig.instances).map(([scriptId, config]) => ({
+    scriptId,
+    type: config.type || 'read-write',
+    deploymentId: config.deploymentId || ''
+  }));
+}
+
+/**
+ * Resolve a single instance by type or scriptId.
+ *
+ * @param {object} envConfig - Environment config
+ * @param {string} identifier - Instance type (e.g. "reader-writer") or scriptId
+ * @returns {{ scriptId: string, type: string, deploymentId: string }}
+ */
+export function getInstanceConfig(envConfig, identifier) {
+  const instances = getAllInstances(envConfig);
+
+  // Try exact scriptId match first
+  const byId = instances.find(i => i.scriptId === identifier);
+  if (byId) return byId;
+
+  // Resolve alias (rw → read-write, r → read-only, w → write-only)
+  const resolved = INSTANCE_TYPE_ALIASES[identifier] || identifier;
+
+  // Try type match
+  const byType = instances.filter(i => i.type === resolved);
+  if (byType.length === 1) return byType[0];
+  if (byType.length > 1) {
+    console.error(`Multiple instances of type "${identifier}". Use the scriptId instead:`);
+    for (const inst of byType) {
+      console.error(`  ${inst.scriptId}`);
+    }
+    process.exit(1);
+  }
+
+  const available = instances.map(i => `${i.type} (${i.scriptId.slice(0, 12)}...)`).join(', ');
+  console.error(`Instance "${identifier}" not found. Available: ${available}`);
+  process.exit(1);
+}
+
+/**
+ * Require an --instance flag or auto-select if only one instance exists.
+ *
+ * @param {object} args - Parsed CLI args
+ * @param {object} envConfig - Environment config
+ * @returns {{ scriptId: string, type: string, deploymentId: string }}
+ */
+export function requireInstance(args, envConfig) {
+  const instances = getAllInstances(envConfig);
+
+  if (instances.length === 0) {
+    console.error('No instances configured for this environment.');
+    console.error('Add a scriptId to instances in api.json.');
+    process.exit(1);
+  }
+
+  // If --instance flag provided, resolve by type or scriptId
+  if (args.instance) {
+    return getInstanceConfig(envConfig, args.instance);
+  }
+
+  // Auto-select if only one instance
+  if (instances.length === 1) {
+    return instances[0];
+  }
+
+  // Multiple instances, no --instance flag
+  console.error('Multiple instances found:');
+  for (const inst of instances) {
+    console.error(`  ${inst.type} → ${inst.scriptId.slice(0, 20)}...`);
+  }
+  console.error('Use --instance <type> to specify which one.');
+  process.exit(1);
+}
+
+// ── Clasp Credentials (clasp 3.x --user profiles) ──
+
+/**
+ * Get the clasp user profile name for a DB project + environment.
+ * Format: "<dbName>--<env>" (e.g., "nostackapps-cms--dev")
+ *
+ * @param {string} dbName - DB project name
+ * @param {string} env    - Environment name
+ * @returns {string} Profile name for clasp --user
+ */
+export function getClaspUserProfile(dbName, env = 'dev') {
+  return `${dbName}--${env}`;
+}
+
+/**
+ * Path to the global .clasprc.json where clasp 3.x stores all named profiles.
+ */
+export function getClasprcPath() {
+  return path.join(process.env.HOME || '~', '.clasprc.json');
+}
+
+/**
+ * Load and parse .clasprc.json. Returns null on failure.
+ */
+function loadClasprc() {
+  const clasprcPath = getClasprcPath();
+  if (!fs.existsSync(clasprcPath)) return null;
+  try {
+    return JSON.parse(fs.readFileSync(clasprcPath, 'utf8'));
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Check if clasp credentials exist for a profile.
+ * Handles both clasp 3.x named profiles (data.tokens.<profile>)
+ * and legacy global format (data.token at root, treated as "default").
+ *
+ * @param {string} profile - The profile name (e.g., "nostackapps-cms--dev" or "default")
+ * @returns {boolean}
+ */
+export function hasClaspProfile(profile) {
+  const data = loadClasprc();
+  if (!data) return false;
+
+  // Clasp 3.x named profiles
+  if (data.tokens?.[profile]) return true;
+
+  // Legacy global format — root-level token counts as "default"
+  if (profile === 'default' && data.token?.access_token) return true;
+
+  return false;
+}
+
+/**
+ * Check if any clasp credentials exist (named or global).
+ * Returns the best available profile name, or null.
+ */
+export function findAvailableClaspProfile(preferredProfile) {
+  const data = loadClasprc();
+  if (!data) return null;
+
+  // Preferred named profile
+  if (data.tokens?.[preferredProfile]) return preferredProfile;
+
+  // Legacy global token → use "default"
+  if (data.token?.access_token) return 'default';
+
+  // Any named profile at all
+  if (data.tokens) {
+    const names = Object.keys(data.tokens);
+    if (names.length > 0) return names[0];
+  }
+
+  return null;
+}
+
+/**
+ * Get the access_token for a profile from .clasprc.json.
+ * Handles both clasp 3.x named profiles and legacy global format.
+ *
+ * @param {string} profile - The profile name
+ * @returns {string|null} Access token or null
+ */
+function getProfileAccessToken(profile) {
+  const data = loadClasprc();
+  if (!data) return null;
+
+  // Clasp 3.x named profiles
+  if (data.tokens?.[profile]?.access_token) {
+    return data.tokens[profile].access_token;
+  }
+
+  // Legacy global format — root-level token counts as "default"
+  if (profile === 'default' && data.token?.access_token) {
+    return data.token.access_token;
+  }
+
+  return null;
+}
+
+/**
+ * Get the full token record for a profile (access_token, refresh_token, clientId, etc).
+ * Handles both named profiles and legacy global format.
+ *
+ * @param {string} profile - The profile name
+ * @returns {{ accessToken: string, refreshToken: string, clientId: string, clientSecret: string } | null}
+ */
+function getProfileTokenRecord(profile) {
+  const data = loadClasprc();
+  if (!data) return null;
+
+  // Clasp 3.x named profiles
+  const namedToken = data.tokens?.[profile];
+  if (namedToken?.access_token) {
+    const oauth = namedToken.oauth2ClientSettings || data.oauth2ClientSettings || {};
+    return {
+      accessToken: namedToken.access_token,
+      refreshToken: namedToken.refresh_token,
+      clientId: oauth.clientId,
+      clientSecret: oauth.clientSecret
+    };
+  }
+
+  // Legacy global format
+  if (profile === 'default' && data.token?.access_token) {
+    const oauth = data.oauth2ClientSettings || {};
+    return {
+      accessToken: data.token.access_token,
+      refreshToken: data.token.refresh_token,
+      clientId: oauth.clientId,
+      clientSecret: oauth.clientSecret
+    };
+  }
+
+  return null;
+}
+
+/**
+ * Refresh an expired access_token using the refresh_token.
+ * Updates .clasprc.json in place with the new token.
+ *
+ * @param {string} profile - The profile name
+ * @returns {Promise<string|null>} New access token or null on failure
+ */
+function refreshAccessToken(profile) {
+  return new Promise((resolve) => {
+    const record = getProfileTokenRecord(profile);
+    if (!record?.refreshToken || !record?.clientId || !record?.clientSecret) {
+      resolve(null);
+      return;
+    }
+
+    const postData = new URLSearchParams({
+      client_id: record.clientId,
+      client_secret: record.clientSecret,
+      refresh_token: record.refreshToken,
+      grant_type: 'refresh_token'
+    }).toString();
+
+    const req = https.request('https://oauth2.googleapis.com/token', {
+      method: 'POST',
+      headers: {
+        'Content-Type': 'application/x-www-form-urlencoded',
+        'Content-Length': Buffer.byteLength(postData)
+      }
+    }, (res) => {
+      let body = '';
+      res.on('data', (chunk) => body += chunk);
+      res.on('end', () => {
+        try {
+          const result = JSON.parse(body);
+          if (!result.access_token) {
+            resolve(null);
+            return;
+          }
+
+          // Update .clasprc.json with new token
+          const clasprcPath = getClasprcPath();
+          const data = loadClasprc();
+          if (data) {
+            const newExpiry = Date.now() + (result.expires_in || 3600) * 1000;
+            if (data.tokens?.[profile]) {
+              data.tokens[profile].access_token = result.access_token;
+              data.tokens[profile].expiry_date = newExpiry;
+            } else if (profile === 'default' && data.token) {
+              data.token.access_token = result.access_token;
+              data.token.expiry_date = newExpiry;
+            }
+            fs.writeFileSync(clasprcPath, JSON.stringify(data) + '\n');
+          }
+
+          resolve(result.access_token);
+        } catch {
+          resolve(null);
+        }
+      });
+    });
+
+    req.on('error', () => resolve(null));
+    req.setTimeout(10000, () => { req.destroy(); resolve(null); });
+    req.write(postData);
+    req.end();
+  });
+}
+
+/**
+ * Get a valid access token for a profile, refreshing if expired.
+ *
+ * @param {string} profile - The profile name
+ * @returns {Promise<string|null>} Valid access token or null
+ */
+async function getValidAccessToken(profile) {
+  const token = getProfileAccessToken(profile);
+  if (!token) return null;
+
+  // Try the existing token first
+  const email = await fetchEmail(token);
+  if (email) return token;
+
+  // Token likely expired — try refresh
+  const newToken = await refreshAccessToken(profile);
+  return newToken;
+}
+
+/**
+ * Fetch email using the Drive API (works with clasp's default scopes).
+ * Falls back to userinfo API if Drive fails.
+ *
+ * @param {string} accessToken
+ * @returns {Promise<string|null>}
+ */
+function fetchEmail(accessToken) {
+  return new Promise((resolve) => {
+    // Drive about endpoint — works with drive.file scope that clasp always has
+    const req = https.get('https://www.googleapis.com/drive/v3/about?fields=user', {
+      headers: { 'Authorization': `Bearer ${accessToken}` }
+    }, (res) => {
+      let body = '';
+      res.on('data', (chunk) => body += chunk);
+      res.on('end', () => {
+        try {
+          const info = JSON.parse(body);
+          resolve(info.user?.emailAddress || null);
+        } catch {
+          resolve(null);
+        }
+      });
+    });
+    req.on('error', () => resolve(null));
+    req.setTimeout(5000, () => { req.destroy(); resolve(null); });
+  });
+}
+
+/**
+ * Get the logged-in email for a clasp user profile.
+ * Automatically refreshes expired tokens.
+ *
+ * @param {string} profile - The profile name
+ * @returns {Promise<string|null>} Email address or null on failure
+ */
+export async function getAccountEmail(profile) {
+  const token = await getValidAccessToken(profile);
+  if (!token) return null;
+  return fetchEmail(token);
+}
+
+/**
+ * Resolve the account for an environment.
+ * Checks DB envConfig first, then root config (.nsaproject.json).
+ *
+ * @param {object} envConfig - DB environment config
+ * @param {string} env       - Environment name
+ * @returns {string} Account email or empty string
+ */
+export function resolveAccount(envConfig, env) {
+  if (envConfig.account) return envConfig.account;
+  const rootEnv = getRootEnvConfig(env);
+  return rootEnv.account || '';
+}
+
+/**
+ * Validate that the logged-in account matches the expected account for the env.
+ *
+ * @param {string} profile   - clasp user profile name
+ * @param {object} envConfig - Environment config (may have .account)
+ * @param {string} env       - Environment name (for root config lookup)
+ * @returns {Promise<{ valid: boolean, email?: string, reason?: string }>}
+ */
+export async function validateAccount(profile, envConfig, env) {
+  const email = await getAccountEmail(profile);
+  if (!email) {
+    return { valid: false, reason: 'Could not determine logged-in account (token may be expired)' };
+  }
+
+  const expected = resolveAccount(envConfig, env);
+  if (expected && email !== expected) {
+    return {
+      valid: false,
+      email,
+      reason: `Account mismatch: expected "${expected}" but logged in as "${email}"`
+    };
+  }
+
+  return { valid: true, email };
+}
+
+/**
+ * Ensure the user is authenticated for a DB project + environment.
+ *
+ * Resolution order:
+ *   1. --inherit flag → use "default" profile
+ *   2. Named profile (dbName--env) → use if exists
+ *   3. Fall back to global/default credentials → use if account matches
+ *
+ * If account is declared in envConfig, validates the logged-in email matches.
+ * If account is empty, stores the detected email for future validation.
+ * Blocks on missing credentials or account mismatch (unless --force).
+ *
+ * Returns the clasp --user flag value: a profile name for named profiles,
+ * or empty string for default/legacy credentials (caller should omit --user).
+ *
+ * @param {string} dbName    - DB project name
+ * @param {object} args      - Parsed CLI args
+ * @param {object} envConfig - Environment config
+ * @param {string} env       - Environment name
+ * @returns {Promise<string>} The clasp --user value (empty string = use default)
+ */
+export async function ensureAuthenticated(dbName, args, envConfig, env) {
+  // --inherit flag: use "default" clasp profile (global login)
+  let profile = args.inherit ? 'default' : getClaspUserProfile(dbName, env);
+
+  // If named profile not found, try falling back to any available credentials
+  if (!hasClaspProfile(profile)) {
+    const fallback = findAvailableClaspProfile(profile);
+    if (fallback) {
+      console.log(`  Named profile "${profile}" not found — falling back to "${fallback}" credentials.`);
+      profile = fallback;
+    } else {
+      console.error(`\nNo clasp credentials found.`);
+      console.error(`Run: npm run login -- --db ${dbName} --env ${env}`);
+      process.exit(1);
+    }
+  }
+
+  // Validate account
+  if (!args.force) {
+    const validation = await validateAccount(profile, envConfig, env);
+    if (!validation.valid) {
+      console.error(`\nAuth error: ${validation.reason}`);
+      if (validation.reason?.includes('mismatch')) {
+        console.error(`Logged-in account does not match the declared account for this environment.`);
+        console.error(`Run: npm run login -- --db ${dbName} --env ${env}`);
+      } else if (validation.reason?.includes('expired')) {
+        console.error(`Run: npm run login -- --db ${dbName} --env ${env}`);
+      }
+      process.exit(1);
+    }
+
+    // Store email in root config if account field was empty
+    const knownAccount = resolveAccount(envConfig, env);
+    if (!knownAccount && validation.email) {
+      const rootConfig = loadRootConfig();
+      if (!rootConfig.environments) rootConfig.environments = {};
+      if (!rootConfig.environments[env]) rootConfig.environments[env] = {};
+      rootConfig.environments[env].account = validation.email;
+      saveRootConfig(rootConfig);
+      console.log(`  Stored account "${validation.email}" in .nsaproject.json`);
+    }
+
+    console.log(`  Using account: ${validation.email} (profile: ${profile})`);
+  } else {
+    console.log(`  Using profile: ${profile} (--force, skipping validation)`);
+  }
+
+  // Return empty string for "default" profile — caller should omit --user flag
+  return profile === 'default' ? '' : profile;
+}
+
+// ── Clasp Run ────────────────────────────
+
+/**
+ * Execute `clasp run <functionName>` from distDir.
+ * Uses clasp 3.x --user flag for credential selection.
+ * Parses JSON result from clasp stdout.
+ *
+ * @param {string} distDir   - dist/<db-name>/ directory (must contain .clasp.json)
+ * @param {string} functionName - GAS function to call
+ * @param {Array}  params    - Array of params (will be JSON-stringified)
+ * @param {object} opts      - Options: { userProfile }
+ * @returns {any} Parsed result from clasp run
+ */
+export function claspRun(distDir, functionName, params = [], { userProfile } = {}) {
+  if (!fs.existsSync(path.join(distDir, '.clasp.json'))) {
+    console.error(`No .clasp.json in ${distDir} — run "npm run build -- --db <name>" first.`);
+    process.exit(1);
+  }
+
+  const paramsJson = JSON.stringify(params);
+  const userFlag = userProfile ? ` --user ${userProfile}` : '';
+  const cmd = `npx --prefer-offline @google/clasp run ${functionName} --params '${paramsJson}'${userFlag}`;
+
+  console.log(`  Running: clasp run ${functionName}`);
+
+  const execOpts = {
+    cwd: distDir,
+    encoding: 'utf8',
+    stdio: ['pipe', 'pipe', 'pipe']
+  };
+
+  try {
+    const result = spawnSync(
+      'npx', ['--prefer-offline', '@google/clasp', 'run', functionName, '--params', paramsJson, ...(userProfile ? ['--user', userProfile] : [])],
+      { cwd: distDir, encoding: 'utf8', timeout: 120000 }
+    );
+
+    const stdout = (result.stdout || '').trim();
+    const stderr = (result.stderr || '').trim();
+
+    if (result.signal) {
+      console.error(`\nclasp run killed by ${result.signal} (timeout?)`);
+      if (stderr) console.error(stderr);
+      if (stdout) console.error(stdout);
+      process.exit(1);
+    }
+
+    if (stderr) {
+      console.log(`  stderr: ${stderr.split('\n')[0]}`);
+    }
+
+    if (result.status !== 0) {
+      console.error(`\nclasp run failed (exit ${result.status}):`);
+      if (stderr) console.error(stderr);
+      if (stdout) console.error(stdout);
+      process.exit(1);
+    }
+
+    // clasp run outputs the result on the last non-empty line
+    const lines = stdout.split('\n').filter(l => l.trim());
+    const lastLine = lines[lines.length - 1];
+
+    if (!lastLine) {
+      return stdout;
+    }
+
+    try {
+      return JSON.parse(lastLine);
+    } catch {
+      // If last line isn't JSON, return the full output
+      return stdout;
+    }
+  } catch (err) {
+    console.error(`\nclasp run error: ${err.message}`);
+    process.exit(1);
+  }
+}
+
+// ── Placeholder Detection ────────────────
+
+/**
+ * Check if a scriptId is a placeholder (not yet created via clasp create).
+ */
+export function isPlaceholderScriptId(scriptId) {
+  return !scriptId || scriptId.startsWith('YOUR_');
+}
+
+// ── .env File Support ────────────────────
+
+/**
+ * Load a .env.<env> file from the project root.
+ * Simple KEY=VALUE parser (strips comments, handles quotes).
+ *
+ * @param {string} env - Environment name (e.g. 'dev', 'prod')
+ * @returns {object} Key-value pairs, empty object if file missing
+ */
+export function loadEnvFile(env) {
+  const envPath = path.join(PROJECT_ROOT, `.env.${env}`);
+  if (!fs.existsSync(envPath)) {
+    return {};
+  }
+
+  const content = fs.readFileSync(envPath, 'utf8');
+  const result = {};
+
+  for (const line of content.split('\n')) {
+    const trimmed = line.trim();
+    if (!trimmed || trimmed.startsWith('#')) continue;
+
+    const eqIdx = trimmed.indexOf('=');
+    if (eqIdx === -1) continue;
+
+    const key = trimmed.slice(0, eqIdx).trim();
+    let value = trimmed.slice(eqIdx + 1).trim();
+
+    // Strip surrounding quotes
+    if ((value.startsWith('"') && value.endsWith('"')) ||
+        (value.startsWith("'") && value.endsWith("'"))) {
+      value = value.slice(1, -1);
+    }
+
+    result[key] = value;
+  }
+
+  return result;
+}
+
+/**
+ * Get environment defaults from .env file.
+ * These serve as fallbacks for project/api config values.
+ *
+ * @param {string} env - Environment name
+ * @returns {{ account?: string, driveFolderId?: string, loggingVerbosity?: number }}
+ */
+export function getEnvDefaults(env) {
+  const envVars = loadEnvFile(env);
+  const defaults = {};
+
+  if (envVars.DEFAULT_ACCOUNT) defaults.account = envVars.DEFAULT_ACCOUNT;
+  if (envVars.DRIVE_ROOT_FOLDER_ID) defaults.driveFolderId = envVars.DRIVE_ROOT_FOLDER_ID;
+  if (envVars.DEFAULT_LOGGING_VERBOSITY) defaults.loggingVerbosity = parseInt(envVars.DEFAULT_LOGGING_VERBOSITY, 10);
+  if (envVars.DDL_API_KEY) defaults.ddlApiKey = envVars.DDL_API_KEY;
+
+  return defaults;
+}
+
+// ── Root Config (.nsaproject.json) ───────
+
+/**
+ * Path to the root project config file.
+ */
+export function getRootConfigPath() {
+  return ROOT_CONFIG_PATH;
+}
+
+/**
+ * Load .nsaproject.json — returns empty structure if not found.
+ *
+ * Shape:
+ *   {
+ *     environments: { dev: { account, projectId, ddlHandler: { scriptId, deploymentId, ddlAdminKey } } },
+ *     projects: { "my-db": { kind: "db" } },
+ *     settings: { loggingVerbosity: 2 }
+ *   }
+ */
+export function loadRootConfig() {
+  if (!fs.existsSync(ROOT_CONFIG_PATH)) {
+    return { environments: {}, projects: {}, settings: {} };
+  }
+  return JSON.parse(fs.readFileSync(ROOT_CONFIG_PATH, 'utf8'));
+}
+
+/**
+ * Save .nsaproject.json.
+ */
+export function saveRootConfig(rootConfig) {
+  fs.writeFileSync(ROOT_CONFIG_PATH, JSON.stringify(rootConfig, null, 2) + '\n');
+}
+
+/**
+ * Get the root env config for a given environment.
+ * Returns { account, projectId, ddlHandler } or empty object.
+ */
+export function getRootEnvConfig(env) {
+  const rootConfig = loadRootConfig();
+  return rootConfig.environments?.[env] || {};
+}
+
+/**
+ * Get root settings (loggingVerbosity, etc.).
+ * DB project settings override these.
+ */
+export function getRootSettings() {
+  const rootConfig = loadRootConfig();
+  return rootConfig.settings || {};
+}
+
+// ── DDL Handler ─────────────────────────
+
+/**
+ * Get the dist directory for the DDL handler.
+ */
+export function getDdlHandlerDistDir() {
+  return path.join(DIST_DIR, DDL_HANDLER_DIST_NAME);
+}
+