nsa-sheets-db-builder 0.0.1-alpha.2 → 4.0.0-alpha.0

package/bin/sheets-deployer.mjs

@@ -74,7 +74,7 @@ const command = process.argv[2];
 const restArgs = process.argv.slice(3);
 
 if (!command || command === '--help' || command === '-h') {
-  console.log('nsa-sheets-db-builder v0.0.1-alpha.2 — Google Sheets database provisioner\n');
+  console.log('nsa-sheets-db-builder v4.0.0-alpha.0 — Google Sheets database provisioner\n');
   console.log('Usage: nsa-sheets-db-builder <command> [options]\n');
   console.log('Commands:');
   const maxLen = Math.max(...Object.keys(COMMANDS).map(k => k.length));
@@ -103,9 +103,8 @@ if (!command || command === '--help' || command === '-h') {
   console.log('  dbs/<name>/rbac.json           RBAC config (if enabled)');
   console.log('  dbs/<name>/views.json          SQL view definitions (if enabled)');
   console.log('\nExamples:');
-  console.log('  nsa-sheets-db-builder init --db my-app --template blog-cms --user me@gmail.com');
+  console.log('  nsa-sheets-db-builder init --db my-app --template blog-cms');
   console.log('  nsa-sheets-db-builder init --db my-app --instances r,w');
-  console.log('  nsa-sheets-db-builder init --db my-app --env prod --user prod@gmail.com');
   console.log('  nsa-sheets-db-builder init --db my-app --rbac request --views');
   console.log('  nsa-sheets-db-builder build --db my-app');
   console.log('  nsa-sheets-db-builder push --db my-app --instance rw');

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "nsa-sheets-db-builder",
-  "version": "0.0.1-alpha.2",
+  "version": "4.0.0-alpha.0",
   "description": "DDL provisioner for Google Sheets — creates spreadsheets, sheets, and headers",
   "type": "module",
   "license": "MIT",
@@ -64,8 +64,10 @@
     "ddl-handler": "node scripts/ddl-handler.mjs"
   },
   "dependencies": {
-    "@google/clasp": "^3.2.0",
     "ejs": "^3.1.10",
     "esbuild": "^0.27.3"
+  },
+  "peerDependencies": {
+    "@google/clasp": ">=3.0.0"
   }
 }

package/scripts/build.mjs

@@ -32,8 +32,7 @@ import {
   getAllInstances, requireInstance, loadTables,
   loadRbacConfig, loadViewsConfig, loadCustomMethodsConfig, getFeatures, validateRbacRequirements,
   getDdlHandlerDistDir, getRootEnvConfig,
-  PACKAGE_ROOT, COMMON_LIBS_DIR, DBS_DIR, ensureAuthenticated,
-  recordDeployment
+  PACKAGE_ROOT, COMMON_LIBS_DIR, DBS_DIR, ensureAuthenticated
 } from './lib/utils.mjs';
 
 // ────────────────────────────────────────
@@ -498,7 +497,6 @@ async function build() {
           execSync(`npx --prefer-offline @google/clasp deploy --description '${desc}'${claspUserFlag(userProfile)}`, { cwd: distDir, stdio: 'inherit' });
           console.log('New deployment created.');
         }
-        recordDeployment(dbName, env);
       } catch {
         console.error('clasp deploy failed.');
         process.exit(1);

package/scripts/ddl-handler.mjs

@@ -12,7 +12,7 @@
  *   - Push it to Apps Script
  *   - Deploy it as a web app
  *
- * The DDL handler reference is stored in .env.<env> (root config)
+ * The DDL handler reference is stored in .nsaproject.json (root config)
  * under environments.<env>.ddlHandler.
  *
  * Usage:
@@ -41,8 +41,8 @@ import { execSync } from 'child_process';
 import {
   parseArgs, requireDb, loadDbConfig, getEnvConfig,
   ensureAuthenticated, resolveAccount,
-  getDdlHandlerDistDir, recordDdlHandlerDeployment,
-  getRootEnvConfig, saveEnvVars
+  loadRootConfig, saveRootConfig,
+  getDdlHandlerDistDir
 } from './lib/utils.mjs';
 import { buildDdlHandler } from './build.mjs';
 
@@ -76,8 +76,8 @@ async function main() {
 
   const account = resolveAccount(envConfig, env);
   if (!account) {
-    console.error('ERROR: CLASP_USER not set.');
-    console.error(`Set CLASP_USER in .env.${env}`);
+    console.error('ERROR: account not set.');
+    console.error(`Set "account" in .nsaproject.json → environments.${env}`);
     process.exit(1);
   }
 
@@ -91,9 +91,10 @@ async function main() {
   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 .env.<env>
-  const rootEnv = getRootEnvConfig(env);
-  const handler = rootEnv.ddlHandler || {};
+  // 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 || '';
@@ -195,14 +196,17 @@ async function main() {
     }
   }
 
-  // ── Save state to .env.<env> ──
+  // ── Save state to .nsaproject.json ──
 
-  saveEnvVars(env, {
-    DDL_HANDLER_SCRIPT_ID: scriptId,
-    DDL_HANDLER_DEPLOYMENT_ID: deploymentId,
-    DDL_HANDLER_ADMIN_KEY: ddlAdminKey
-  });
-  recordDdlHandlerDeployment(env);
+  rootConfig = loadRootConfig();
+  if (!rootConfig.environments) rootConfig.environments = {};
+  if (!rootConfig.environments[env]) rootConfig.environments[env] = {};
+  rootConfig.environments[env].ddlHandler = {
+    scriptId,
+    deploymentId,
+    ddlAdminKey
+  };
+  saveRootConfig(rootConfig);
 
   // ── Summary ──
 
@@ -213,7 +217,7 @@ async function main() {
     console.log(`  Web app:       https://script.google.com/macros/s/${deploymentId}/exec`);
   }
   console.log(`  Admin key:     ${ddlAdminKey.substring(0, 8)}...`);
-  console.log(`  Saved to:      .env.<env>`);
+  console.log(`  Saved to:      .nsaproject.json`);
 
   if (doDeploy && !handler.deploymentId) {
     console.log(`\n  NOTE: Authorize the DDL handler in the Apps Script editor:`);

package/scripts/init.mjs

@@ -9,7 +9,6 @@
  *   node scripts/init.mjs --db <name> --instances r,w
  *   node scripts/init.mjs --db <name> --auth simple --rbac
  *   node scripts/init.mjs --db <name> --views
- *   node scripts/init.mjs --db <name> --env dev --user me@gmail.com
  *
  * Interactive: prompts for template selection if --template not given.
  * Non-interactive: use --template to skip the prompt.
@@ -25,8 +24,6 @@
  *   --rbac        Enable role-based access control. Scaffolds rbac.json + users/roles tables.
  *                 Requires --auth simple or --auth google.
  *   --views       Enable SQL views support. Scaffolds views.json.
- *   --env         Target environment to set --user for (default: dev)
- *   --user        Expected Google account email for the environment
  *
  * Creates:
  *   dbs/<name>/project.json   — all config (name, settings, authMode, features, environments)
@@ -43,8 +40,7 @@ import readline from 'readline';
 import {
   parseArgs, PACKAGE_ROOT, DBS_DIR, COMMON_LIBS_DIR,
   getEnvDefaults, resolveInstanceType,
-  loadRootConfig, saveRootConfig, getStateLockPath,
-  createEnvFile, saveEnvVar
+  loadRootConfig, saveRootConfig
 } from './lib/utils.mjs';
 
 const TEMPLATES_DIR = path.join(PACKAGE_ROOT, 'templates');
@@ -119,24 +115,12 @@ function resolveInstances(args) {
   if (args.instances && typeof args.instances === 'string') {
     const inputs = args.instances.split(',').map(s => s.trim()).filter(Boolean);
     const types = inputs.map(resolveInstanceType);
-
-    if (types.length === 1) {
-      instances['YOUR_SCRIPT_ID'] = { type: types[0], deploymentId: '' };
-    } else {
-      // Count occurrences of each type to decide numbering
-      const typeCounts = {};
-      for (const t of types) typeCounts[t] = (typeCounts[t] || 0) + 1;
-
-      const typeIdx = {};
-      for (const type of types) {
-        const tag = type.toUpperCase().replace(/-/g, '_');
-        if (typeCounts[type] > 1) {
-          typeIdx[type] = (typeIdx[type] || 0) + 1;
-          instances[`YOUR_${tag}_${typeIdx[type]}_SCRIPT_ID`] = { type, deploymentId: '' };
-        } else {
-          instances[`YOUR_${tag}_SCRIPT_ID`] = { type, deploymentId: '' };
-        }
-      }
+    for (const type of types) {
+      const placeholder = types.length === 1 ? 'YOUR_SCRIPT_ID' : `YOUR_${type.toUpperCase().replace(/-/g, '_')}_SCRIPT_ID`;
+      instances[placeholder] = {
+        type,
+        deploymentId: ''
+      };
     }
   } else {
     instances['YOUR_SCRIPT_ID'] = {
@@ -316,7 +300,7 @@ async function main() {
   const args = parseArgs();
 
   if (!args.db) {
-    console.error('Usage: node scripts/init.mjs --db <name> [--template <template>] [--instances rw,r,w] [--auth noAuth|simple|google] [--rbac] [--views] [--env <env>] [--user <email>]');
+    console.error('Usage: node scripts/init.mjs --db <name> [--template <template>] [--instances rw,r,w] [--auth noAuth|simple|google] [--rbac] [--views]');
     process.exit(1);
   }
 
@@ -403,9 +387,6 @@ async function main() {
   fs.writeFileSync(path.join(dbDir, 'project.json'), generateProjectJson(dbName, instances, envDefaults, features, authMode));
   fs.writeFileSync(path.join(dbDir, 'tables.json'), generateTablesJson(tables));
 
-  // Create empty state lock file
-  fs.writeFileSync(getStateLockPath(dbName), JSON.stringify({ schemaVersion: 1, environments: {} }, null, 2) + '\n');
-
   // RBAC config
   if (features.rbac) {
     fs.writeFileSync(path.join(dbDir, 'rbac.json'), generateRbacJson());
@@ -436,26 +417,32 @@ async function main() {
   // Register project in .nsaproject.json
   const rootConfig = loadRootConfig();
   if (!rootConfig.kind) rootConfig.kind = 'db';
-  if (!Array.isArray(rootConfig.projects)) rootConfig.projects = [];
+  if (!rootConfig.environments) rootConfig.environments = {};
+  if (!rootConfig.projects) rootConfig.projects = [];
+
+  // Ensure env entries exist
+  for (const envName of ['dev', 'prod']) {
+    if (!rootConfig.environments[envName]) {
+      rootConfig.environments[envName] = {
+        account: '',
+        projectId: '',
+        ddlHandler: { scriptId: '', deploymentId: '', ddlAdminKey: '' }
+      };
+    }
+  }
 
+  // Store account from env defaults if available and not already set
+  if (envDefaults.account && !rootConfig.environments.dev.account) {
+    rootConfig.environments.dev.account = envDefaults.account;
+  }
+
+  // Add project to registry if not already listed
   if (!rootConfig.projects.includes(dbName)) {
     rootConfig.projects.push(dbName);
   }
 
   saveRootConfig(rootConfig);
 
-  // Create .env.<env> files if they don't exist
-  const targetEnv = args.env || 'dev';
-  const userAccount = args.user || envDefaults.account || '';
-
-  createEnvFile('dev', { account: targetEnv === 'dev' ? userAccount : '' });
-  createEnvFile('prod', { account: targetEnv === 'prod' ? userAccount : '' });
-
-  // If --user provided for a specific env, update that env file
-  if (userAccount) {
-    saveEnvVar(targetEnv, 'CLASP_USER', userAccount);
-  }
-
   const tableNames = Object.keys(tables);
   const instanceKeys = Object.keys(instances);
   console.log(`\nCreated DB project: ${dbName}`);

package/scripts/lib/utils.mjs

@@ -46,7 +46,6 @@ 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');
-const ROOT_LOCK_PATH = path.join(PROJECT_ROOT, '.nsaproject.lock.json');
 
 // DDL Handler dist directory
 const DDL_HANDLER_DIST_NAME = '__ddl-handler__';
@@ -95,23 +94,18 @@ export function requireDb(args, scriptName) {
 // ── Config I/O ───────────────────────────
 //
 // Project layout:
-//   dbs/<name>/project.json        — config (name, settings, authMode, instances, features)
-//   dbs/<name>/state.lock.json     — deployment state (auto-generated, do not edit)
-//   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
+//   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 getStateLockPath(dbName) {
-  return path.join(DBS_DIR, dbName, 'state.lock.json');
-}
-
 export function getTablesPath(dbName) {
   return path.join(DBS_DIR, dbName, 'tables.json');
 }
@@ -157,116 +151,13 @@ export function loadDbConfig(dbName) {
 }
 
 /**
- * Save project.json (config only: name, settings, authMode, instances, features).
+ * 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');
 }
 
-// ── State Lock I/O (per-DB) ─────────────
-//
-// state.lock.json — auto-generated metadata, do not edit manually.
-// Tracks schema hashes, deployment timestamps, and migration history.
-// The source of truth for "what's deployed" remains project.json + tables.json.
-//
-// Shape:
-//   {
-//     schemaVersion: 1,
-//     environments: {
-//       dev: {
-//         lastDeployed: "2026-02-11T16:44:00Z",
-//         tables: {
-//           "users": { schemaHash: "a3f2c1...", lastProvisioned: "2026-02-11T..." }
-//         },
-//         migrations: [
-//           { id: 1, applied: "2026-02-11T...", description: "Initial schema" }
-//         ]
-//       }
-//     }
-//   }
-
-/**
- * Load state.lock.json — returns empty structure if not found.
- */
-export function loadStateLock(dbName) {
-  const p = getStateLockPath(dbName);
-  if (!fs.existsSync(p)) {
-    return { schemaVersion: 1, environments: {} };
-  }
-  return JSON.parse(fs.readFileSync(p, 'utf8'));
-}
-
-/**
- * Save state.lock.json.
- */
-export function saveStateLock(dbName, state) {
-  const p = getStateLockPath(dbName);
-  state.lastUpdated = new Date().toISOString();
-  fs.writeFileSync(p, JSON.stringify(state, null, 2) + '\n');
-}
-
-/**
- * Get environment state from state.lock.json.
- */
-export function getEnvState(state, envName) {
-  const env = envName || 'dev';
-  return state.environments?.[env] || {};
-}
-
-/**
- * Ensure an environment entry exists in state lock and return it (mutable reference).
- */
-export function ensureEnvState(state, envName) {
-  const env = envName || 'dev';
-  if (!state.environments) state.environments = {};
-  if (!state.environments[env]) {
-    state.environments[env] = {
-      lastDeployed: null,
-      tables: {},
-      migrations: []
-    };
-  }
-  return state.environments[env];
-}
-
-/**
- * Compute a simple hash of a table schema for drift detection.
- */
-export function computeSchemaHash(tableDefinition) {
-  const str = JSON.stringify(tableDefinition.schema || {});
-  let hash = 0;
-  for (let i = 0; i < str.length; i++) {
-    const chr = str.charCodeAt(i);
-    hash = ((hash << 5) - hash) + chr;
-    hash |= 0;
-  }
-  return Math.abs(hash).toString(36);
-}
-
-/**
- * Record table provisioning state in the lock file.
- */
-export function recordTableState(dbName, env, tableName, tableDefinition) {
-  const state = loadStateLock(dbName);
-  const envState = ensureEnvState(state, env);
-  envState.tables[tableName] = {
-    schemaHash: computeSchemaHash(tableDefinition),
-    lastProvisioned: new Date().toISOString()
-  };
-  saveStateLock(dbName, state);
-}
-
-/**
- * Record a deployment in the lock file.
- */
-export function recordDeployment(dbName, env) {
-  const state = loadStateLock(dbName);
-  const envState = ensureEnvState(state, env);
-  envState.lastDeployed = new Date().toISOString();
-  saveStateLock(dbName, state);
-}
-
 /**
  * Load tables.json — exits if not found.
  */
@@ -370,7 +261,7 @@ export function validateRbacRequirements(tables, rbacConfig) {
 
 /**
  * Resolve environment config — uses --env flag or defaults to 'dev'.
- * Returns { env, envConfig } where envConfig has instances, spreadsheetId, etc.
+ * Returns { env, envConfig } where envConfig has instances, account, spreadsheetId.
  */
 export function getEnvConfig(config, envOverride) {
   const env = envOverride || 'dev';
@@ -431,10 +322,8 @@ export function getDistDirForInstance(dbName, instanceType) {
 
 // ── Instance Helpers ─────────────────────
 //
-// State lock shape: instances keyed by scriptId, value has type + deploymentId + ddlAdminKey.
-//   "instances": { "SCRIPT_ID": { "type": "read-write", "deploymentId": "", "ddlAdminKey": "" } }
-//
-// Config shape: instances is an array of type strings: ["read-write", "read-only"]
+// 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.
 
@@ -462,7 +351,7 @@ export function resolveInstanceType(input) {
  * Get all instances for an environment config.
  * Each entry: { scriptId, type, deploymentId }
  *
- * @param {object} envConfig - Environment config from project.json
+ * @param {object} envConfig - Environment config
  * @returns {Array<{ scriptId: string, type: string, deploymentId: string }>}
  */
 export function getAllInstances(envConfig) {
@@ -477,8 +366,8 @@ export function getAllInstances(envConfig) {
 /**
  * Resolve a single instance by type or scriptId.
  *
- * @param {object} envConfig - Environment config from project.json
- * @param {string} identifier - Instance type (e.g. "read-write") 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) {
@@ -511,7 +400,7 @@ export function getInstanceConfig(envConfig, identifier) {
  * Require an --instance flag or auto-select if only one instance exists.
  *
  * @param {object} args - Parsed CLI args
- * @param {object} envConfig - Environment config from project.json
+ * @param {object} envConfig - Environment config
  * @returns {{ scriptId: string, type: string, deploymentId: string }}
  */
 export function requireInstance(args, envConfig) {
@@ -812,13 +701,14 @@ export async function getAccountEmail(profile) {
 
 /**
  * Resolve the account for an environment.
- * Reads from .env.<env> file — account is env-level.
+ * Checks DB envConfig first, then root config (.nsaproject.json).
  *
- * @param {object} envConfig - DB environment config (unused, kept for compat)
+ * @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 || '';
 }
@@ -882,7 +772,7 @@ export async function ensureAuthenticated(dbName, args, envConfig, env) {
       profile = fallback;
     } else {
       console.error(`\nNo clasp credentials found.`);
-      console.error(`Run: nsa-sheets-db-builder login --db ${dbName} --env ${env}`);
+      console.error(`Run: npm run login -- --db ${dbName} --env ${env}`);
       process.exit(1);
     }
   }
@@ -894,18 +784,22 @@ export async function ensureAuthenticated(dbName, args, envConfig, env) {
       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: nsa-sheets-db-builder login --db ${dbName} --env ${env}`);
+        console.error(`Run: npm run login -- --db ${dbName} --env ${env}`);
       } else if (validation.reason?.includes('expired')) {
-        console.error(`Run: nsa-sheets-db-builder login --db ${dbName} --env ${env}`);
+        console.error(`Run: npm run login -- --db ${dbName} --env ${env}`);
       }
       process.exit(1);
     }
 
-    // Store email in env file if account field was empty
+    // Store email in root config if account field was empty
     const knownAccount = resolveAccount(envConfig, env);
     if (!knownAccount && validation.email) {
-      saveEnvVar(env, 'CLASP_USER', validation.email);
-      console.log(`  Stored account "${validation.email}" in .env.${env}`);
+      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})`);
@@ -1004,25 +898,7 @@ export function isPlaceholderScriptId(scriptId) {
   return !scriptId || scriptId.startsWith('YOUR_');
 }
 
-// ── .env.<env> File Support ──────────────
-//
-// Environment-level config lives in .env.<env> files (mandatory).
-// These are the single source of truth for account, projectId, DDL handler, etc.
-//
-// .env.dev:
-//   CLASP_USER=me@gmail.com
-//   GCP_PROJECT_ID=354563759750
-//   DDL_HANDLER_SCRIPT_ID=1abc...
-//   DDL_HANDLER_DEPLOYMENT_ID=AKfyc...
-//   DDL_HANDLER_ADMIN_KEY=a1b2c3...
-//   DRIVE_ROOT_FOLDER_ID=           (optional)
-
-/**
- * Get the path to an env file.
- */
-export function getEnvFilePath(env) {
-  return path.join(PROJECT_ROOT, `.env.${env}`);
-}
+// ── .env File Support ────────────────────
 
 /**
  * Load a .env.<env> file from the project root.
@@ -1032,7 +908,7 @@ export function getEnvFilePath(env) {
  * @returns {object} Key-value pairs, empty object if file missing
  */
 export function loadEnvFile(env) {
-  const envPath = getEnvFilePath(env);
+  const envPath = path.join(PROJECT_ROOT, `.env.${env}`);
   if (!fs.existsSync(envPath)) {
     return {};
   }
@@ -1063,145 +939,25 @@ export function loadEnvFile(env) {
 }
 
 /**
- * Save/update a key-value pair in .env.<env> file.
- * Creates the file if it doesn't exist. Updates existing key in place.
- *
- * @param {string} env - Environment name
- * @param {string} key - Variable name
- * @param {string} value - Variable value
- */
-export function saveEnvVar(env, key, value) {
-  const envPath = getEnvFilePath(env);
-  let lines = [];
-
-  if (fs.existsSync(envPath)) {
-    lines = fs.readFileSync(envPath, 'utf8').split('\n');
-  }
-
-  // Find existing key and update, or append
-  let found = false;
-  for (let i = 0; i < lines.length; i++) {
-    const trimmed = lines[i].trim();
-    if (trimmed.startsWith('#') || !trimmed) continue;
-    const eqIdx = trimmed.indexOf('=');
-    if (eqIdx === -1) continue;
-    if (trimmed.slice(0, eqIdx).trim() === key) {
-      lines[i] = `${key}=${value}`;
-      found = true;
-      break;
-    }
-  }
-
-  if (!found) {
-    // Ensure trailing newline before appending
-    if (lines.length > 0 && lines[lines.length - 1] !== '') {
-      lines.push('');
-    }
-    lines.push(`${key}=${value}`);
-  }
-
-  // Ensure file ends with newline
-  const content = lines.join('\n').replace(/\n*$/, '\n');
-  fs.writeFileSync(envPath, content);
-}
-
-/**
- * Save multiple key-value pairs to .env.<env> file.
- */
-export function saveEnvVars(env, vars) {
-  for (const [key, value] of Object.entries(vars)) {
-    saveEnvVar(env, key, value);
-  }
-}
-
-/**
- * Create a .env.<env> file with initial values.
- * Only creates if file doesn't already exist.
+ * Get environment defaults from .env file.
+ * These serve as fallbacks for project/api config values.
  *
  * @param {string} env - Environment name
- * @param {object} vars - Initial key-value pairs
- */
-export function createEnvFile(env, vars = {}) {
-  const envPath = getEnvFilePath(env);
-  if (fs.existsSync(envPath)) return;
-
-  const lines = [
-    `# .env.${env} — environment config for nsa-sheets-db-builder`,
-    `# Auto-generated. Edit values as needed.`,
-    '',
-    '# Google account used for clasp login',
-    `CLASP_USER=${vars.account || ''}`,
-    '',
-    '# Google Cloud project ID (for GAS deployment)',
-    `GCP_PROJECT_ID=${vars.projectId || ''}`,
-    '',
-    '# DDL Handler (shared per account — auto-populated by setup)',
-    `DDL_HANDLER_SCRIPT_ID=${vars.ddlHandlerScriptId || ''}`,
-    `DDL_HANDLER_DEPLOYMENT_ID=${vars.ddlHandlerDeploymentId || ''}`,
-    `DDL_HANDLER_ADMIN_KEY=${vars.ddlHandlerAdminKey || ''}`,
-    '',
-    '# Optional',
-    `DRIVE_ROOT_FOLDER_ID=${vars.driveFolderId || ''}`,
-    ''
-  ];
-
-  fs.writeFileSync(envPath, lines.join('\n'));
-}
-
-/**
- * Require an env file to exist, or exit with error.
- */
-export function requireEnvFile(env) {
-  const envPath = getEnvFilePath(env);
-  if (!fs.existsSync(envPath)) {
-    console.error(`Missing .env.${env} file at ${envPath}`);
-    console.error(`Run "nsa-sheets-db-builder init" to create one, or create it manually.`);
-    process.exit(1);
-  }
-}
-
-/**
- * Get environment config from .env.<env> file.
- * This is the primary source for env-level vars.
- *
- * @param {string} env - Environment name
- * @returns {{ account, projectId, ddlHandler: { scriptId, deploymentId, ddlAdminKey }, driveFolderId }}
- */
-export function getRootEnvConfig(env) {
-  const vars = loadEnvFile(env);
-  return {
-    account: vars.CLASP_USER || '',
-    projectId: vars.GCP_PROJECT_ID || '',
-    ddlHandler: {
-      scriptId: vars.DDL_HANDLER_SCRIPT_ID || '',
-      deploymentId: vars.DDL_HANDLER_DEPLOYMENT_ID || '',
-      ddlAdminKey: vars.DDL_HANDLER_ADMIN_KEY || ''
-    },
-    driveFolderId: vars.DRIVE_ROOT_FOLDER_ID || ''
-  };
-}
-
-/**
- * Get environment defaults from .env file (alias for backward compat).
+ * @returns {{ account?: string, driveFolderId?: string, loggingVerbosity?: number }}
  */
 export function getEnvDefaults(env) {
-  const vars = loadEnvFile(env);
+  const envVars = loadEnvFile(env);
   const defaults = {};
 
-  if (vars.CLASP_USER) defaults.account = vars.CLASP_USER;
-  if (vars.DRIVE_ROOT_FOLDER_ID) defaults.driveFolderId = vars.DRIVE_ROOT_FOLDER_ID;
+  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) ───────
-//
-// Project registry only — no environment data (that's in .env.<env> files).
-// Shape:
-//   {
-//     kind: "db",
-//     projects: ["my-blog", "my-crm"]
-//   }
 
 /**
  * Path to the root project config file.
@@ -1212,10 +968,17 @@ export function getRootConfigPath() {
 
 /**
  * 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 { projects: [] };
+    return { environments: {}, projects: {}, settings: {} };
   }
   return JSON.parse(fs.readFileSync(ROOT_CONFIG_PATH, 'utf8'));
 }
@@ -1228,73 +991,21 @@ export function saveRootConfig(rootConfig) {
 }
 
 /**
- * Get root settings (loggingVerbosity, etc.).
- * DB project settings override these.
+ * Get the root env config for a given environment.
+ * Returns { account, projectId, ddlHandler } or empty object.
  */
-export function getRootSettings() {
+export function getRootEnvConfig(env) {
   const rootConfig = loadRootConfig();
-  return rootConfig.settings || {};
-}
-
-// ── Root Lock (.nsaproject.lock.json) ────
-//
-// Auto-generated metadata — do not edit manually.
-// Tracks deployment timestamps and DDL handler usage state.
-// The source of truth for DDL handler config stays in .nsaproject.json.
-//
-// Shape:
-//   {
-//     environments: {
-//       dev: {
-//         ddlHandler: { lastDeployed: "2026-02-11T...", lastUsed: "2026-02-11T..." }
-//       }
-//     }
-//   }
-
-export function getRootLockPath() {
-  return ROOT_LOCK_PATH;
-}
-
-/**
- * Load .nsaproject.lock.json — returns empty structure if not found.
- */
-export function loadRootLock() {
-  if (!fs.existsSync(ROOT_LOCK_PATH)) {
-    return { environments: {} };
-  }
-  return JSON.parse(fs.readFileSync(ROOT_LOCK_PATH, 'utf8'));
-}
-
-/**
- * Save .nsaproject.lock.json.
- */
-export function saveRootLock(rootLock) {
-  rootLock.lastUpdated = new Date().toISOString();
-  fs.writeFileSync(ROOT_LOCK_PATH, JSON.stringify(rootLock, null, 2) + '\n');
+  return rootConfig.environments?.[env] || {};
 }
 
 /**
- * Record DDL handler deployment in root lock.
- */
-export function recordDdlHandlerDeployment(env) {
-  const rootLock = loadRootLock();
-  if (!rootLock.environments) rootLock.environments = {};
-  if (!rootLock.environments[env]) rootLock.environments[env] = {};
-  if (!rootLock.environments[env].ddlHandler) rootLock.environments[env].ddlHandler = {};
-  rootLock.environments[env].ddlHandler.lastDeployed = new Date().toISOString();
-  saveRootLock(rootLock);
-}
-
-/**
- * Record DDL handler usage in root lock.
+ * Get root settings (loggingVerbosity, etc.).
+ * DB project settings override these.
  */
-export function recordDdlHandlerUsage(env) {
-  const rootLock = loadRootLock();
-  if (!rootLock.environments) rootLock.environments = {};
-  if (!rootLock.environments[env]) rootLock.environments[env] = {};
-  if (!rootLock.environments[env].ddlHandler) rootLock.environments[env].ddlHandler = {};
-  rootLock.environments[env].ddlHandler.lastUsed = new Date().toISOString();
-  saveRootLock(rootLock);
+export function getRootSettings() {
+  const rootConfig = loadRootConfig();
+  return rootConfig.settings || {};
 }
 
 // ── DDL Handler ─────────────────────────

package/scripts/login.mjs

@@ -7,15 +7,15 @@
  *   node scripts/login.mjs --db <name> [--env <env>] [--account user@gmail.com]
  *
  * Flow:
- *   1. Ask for the Gmail account (or use --account flag / existing .env.<env>)
+ *   1. Ask for the Gmail account (or use --account flag / existing config)
  *   2. Run `clasp login --user <dbName>--<env>`
  *   3. Verify the logged-in account matches the specified one
- *   4. Store email in .env.<env> → CLASP_USER
+ *   4. Store email in .nsaproject.json → environments.<env>.account
  */
 
 import readline from 'readline';
 import { execSync } from 'child_process';
-import { parseArgs, requireDb, loadDbConfig, getEnvConfig, getClaspUserProfile, getAccountEmail, resolveAccount, saveEnvVar } from './lib/utils.mjs';
+import { parseArgs, requireDb, loadDbConfig, getEnvConfig, getClaspUserProfile, getAccountEmail, resolveAccount, loadRootConfig, saveRootConfig } from './lib/utils.mjs';
 
 function prompt(question) {
   const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
@@ -72,7 +72,11 @@ const actualEmail = await getAccountEmail(profile);
 if (!actualEmail) {
   console.warn('\nWarning: Could not verify account email (token may not have userinfo scope).');
   console.log('Saving specified account to config anyway.\n');
-  saveEnvVar(env, 'CLASP_USER', expectedAccount);
+  const rc1 = loadRootConfig();
+  if (!rc1.environments) rc1.environments = {};
+  if (!rc1.environments[env]) rc1.environments[env] = {};
+  rc1.environments[env].account = expectedAccount;
+  saveRootConfig(rc1);
   console.log(`Login complete for ${dbName} (${env})`);
   console.log(`  Profile: ${profile}`);
   console.log(`  Account (unverified): ${expectedAccount}`);
@@ -87,8 +91,12 @@ if (actualEmail.toLowerCase() !== expectedAccount.toLowerCase()) {
   process.exit(1);
 }
 
-// 4. Store account in .env.<env>
-saveEnvVar(env, 'CLASP_USER', actualEmail);
+// 4. Store account in root config
+const rc2 = loadRootConfig();
+if (!rc2.environments) rc2.environments = {};
+if (!rc2.environments[env]) rc2.environments[env] = {};
+rc2.environments[env].account = actualEmail;
+saveRootConfig(rc2);
 
 console.log(`\nLogged in as ${actualEmail} for ${dbName} (${env})`);
 console.log(`  Profile: ${profile}`);

package/scripts/provision.mjs

@@ -7,7 +7,7 @@
  *   node scripts/provision.mjs --db <name> [--env <env>] [--instance <type>]
  */
 
-import { parseArgs, requireDb, loadDbConfig, getEnvConfig, getDistDirForInstance, claspRun, loadTables, requireDataSpreadsheet, requireInstance, ensureAuthenticated, recordTableState } from './lib/utils.mjs';
+import { parseArgs, requireDb, loadDbConfig, getEnvConfig, getDistDirForInstance, claspRun, loadTables, requireDataSpreadsheet, requireInstance, ensureAuthenticated } from './lib/utils.mjs';
 
 const args = parseArgs();
 const dbName = requireDb(args, 'provision.mjs');
@@ -33,8 +33,3 @@ const result = claspRun(distDir, 'ddlProvisionTables', [{
 }], { userProfile });
 
 console.log('\nResult:', JSON.stringify(result, null, 2));
-
-// Record table state in lock file
-for (const [tableName, tableDef] of Object.entries(tables)) {
-  recordTableState(dbName, env, tableName, tableDef);
-}

package/scripts/setup.mjs

@@ -36,10 +36,8 @@ import {
   getFeatures, validateRbacRequirements,
   ensureAuthenticated, isPlaceholderScriptId,
   getDataSpreadsheetIds,
-  resolveAccount,
-  getDdlHandlerDistDir,
-  recordDdlHandlerDeployment, recordDeployment, recordTableState,
-  getRootEnvConfig, saveEnvVars
+  loadRootConfig, saveRootConfig, resolveAccount,
+  getDdlHandlerDistDir
 } from './lib/utils.mjs';
 import { buildInstance, buildDdlHandler, getDeploymentDescription } from './build.mjs';
 
@@ -246,14 +244,15 @@ async function setup() {
 
   const account = resolveAccount(envConfig, env);
   if (!account) {
-    console.error('  ERROR: CLASP_USER not set.');
-    console.error(`  Set CLASP_USER in .env.${env}`);
+    console.error('  ERROR: account not set.');
+    console.error('  Set "account" in .nsaproject.json → environments.' + env);
     console.error('  Or run login first to auto-detect.');
     process.exit(1);
   }
 
-  // Resolve DDL handler from .env.<env>
-  const rootEnv = getRootEnvConfig(env);
+  // Resolve DDL handler from root config (.nsaproject.json)
+  let rootConfig = loadRootConfig();
+  let rootEnv = rootConfig.environments?.[env] || {};
   let ddlHandler = rootEnv.ddlHandler || {};
 
   if (ddlHandler.scriptId && ddlHandler.deploymentId) {
@@ -342,16 +341,18 @@ async function setup() {
       console.log(`  deploymentId: ${handlerDeploymentId}`);
     }
 
-    // f. Save to .env.<env>
-    saveEnvVars(env, {
-      DDL_HANDLER_SCRIPT_ID: handlerScriptId,
-      DDL_HANDLER_DEPLOYMENT_ID: handlerDeploymentId,
-      DDL_HANDLER_ADMIN_KEY: handlerAdminKey
-    });
-    recordDdlHandlerDeployment(env);
-    ddlHandler = { scriptId: handlerScriptId, deploymentId: handlerDeploymentId, ddlAdminKey: handlerAdminKey };
+    // f. Save to .nsaproject.json
+    if (!rootConfig.environments) rootConfig.environments = {};
+    if (!rootConfig.environments[env]) rootConfig.environments[env] = {};
+    rootConfig.environments[env].ddlHandler = {
+      scriptId: handlerScriptId,
+      deploymentId: handlerDeploymentId,
+      ddlAdminKey: handlerAdminKey
+    };
+    saveRootConfig(rootConfig);
+    ddlHandler = rootConfig.environments[env].ddlHandler;
 
-    console.log(`\n  DDL handler saved to .env.${env}`);
+    console.log(`\n  DDL handler saved to .nsaproject.json`);
 
     // g. Print authorization reminder
     console.log(`\n  IMPORTANT: Authorize the DDL handler in the Apps Script editor:`);
@@ -570,7 +571,6 @@ async function setup() {
         process.exit(1);
       }
     }
-    recordDeployment(dbName, env);
     console.log('\n  Re-build + re-push + re-deploy complete.');
   }
 
@@ -604,11 +604,6 @@ async function setup() {
   }
   console.log('  Provision result:', JSON.stringify(provisionResult, null, 2));
 
-  // Record table state in lock file
-  for (const [tableName, tableDef] of Object.entries(tables)) {
-    recordTableState(dbName, env, tableName, tableDef);
-  }
-
   // ── Step 10: Rotate API keys (via DB script web app) ──
 
   step(10, 'Rotate API keys');