nsa-sheets-db-builder 4.0.0

package/scripts/init.mjs

@@ -0,0 +1,465 @@
+#!/usr/bin/env node
+
+/**
+ * Initialize a new DB project from a template.
+ *
+ * Usage:
+ *   node scripts/init.mjs --db <name>
+ *   node scripts/init.mjs --db <name> --template <template>
+ *   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
+ *
+ * Interactive: prompts for template selection if --template not given.
+ * Non-interactive: use --template to skip the prompt.
+ *
+ * Flags:
+ *   --instances   Comma-separated instance types: rw, r, w (or read-write, read-only, write-only)
+ *                 Default: single read-write (rw) instance
+ *   --auth        Authentication mode: noAuth, simple, google
+ *                   noAuth  — no authentication, audit "who" = "system"
+ *                   simple  — user email + passphrase in request body
+ *                   google  — Google Workspace SSO (Session.getActiveUser())
+ *                 Default: noAuth
+ *   --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.
+ *
+ * Creates:
+ *   dbs/<name>/project.json   — all config (name, settings, authMode, features, environments)
+ *   dbs/<name>/tables.json    — table definitions (from template)
+ *   dbs/<name>/libs/          — scaffolded library source files (.ts + .js)
+ *   dbs/<name>/methods/       — custom method handlers (empty scaffold)
+ *   dbs/<name>/rbac.json      — RBAC config (if --rbac)
+ *   dbs/<name>/views.json     — SQL view definitions (if --views)
+ */
+
+import fs from 'fs';
+import path from 'path';
+import readline from 'readline';
+import {
+  parseArgs, PACKAGE_ROOT, DBS_DIR, COMMON_LIBS_DIR,
+  getEnvDefaults, resolveInstanceType,
+  loadRootConfig, saveRootConfig
+} from './lib/utils.mjs';
+
+const TEMPLATES_DIR = path.join(PACKAGE_ROOT, 'templates');
+
+/**
+ * Library scaffold order — dependency-aware.
+ * Each entry: { name, file, source }
+ * source: 'local' = libs/ in package, 'common' = common/libs/
+ */
+const LIB_SCAFFOLD_ORDER = [
+  { name: 'gaserror',            file: 'gaserror.ts',            source: 'common' },
+  { name: 'gaslogger',           file: 'gaslogger.ts',           source: 'common' },
+  { name: 'gas_response_helper', file: 'gas_response_helper.ts', source: 'common' },
+  { name: 'spreadsheets_db',     file: 'spreadsheets_db.ts',     source: 'local'  },
+  { name: 'db_ddl',              file: 'db_ddl.ts',              source: 'local'  },
+  { name: 'triggers',            file: 'triggers.ts',            source: 'local'  },
+  { name: 'alasql',              file: 'alasql.js',              source: 'local', native: true }
+];
+
+function loadTemplates() {
+  const files = fs.readdirSync(TEMPLATES_DIR).filter(f => f.endsWith('.json'));
+  const templates = [];
+  for (const file of files) {
+    const data = JSON.parse(fs.readFileSync(path.join(TEMPLATES_DIR, file), 'utf8'));
+    templates.push(data);
+  }
+  return templates;
+}
+
+function ask(rl, question) {
+  return new Promise(resolve => rl.question(question, resolve));
+}
+
+/**
+ * Scaffold library .ts files into dbs/<name>/libs/ with numeric prefixes.
+ * Files are copied from the package — user can edit them afterward.
+ */
+function scaffoldLibs(libsDir) {
+  fs.mkdirSync(libsDir, { recursive: true });
+  let copied = 0;
+
+  for (let i = 0; i < LIB_SCAFFOLD_ORDER.length; i++) {
+    const lib = LIB_SCAFFOLD_ORDER[i];
+    const srcDir = lib.source === 'common'
+      ? COMMON_LIBS_DIR
+      : path.join(PACKAGE_ROOT, 'libs');
+    const srcPath = path.join(srcDir, lib.file);
+
+    if (!fs.existsSync(srcPath)) {
+      console.warn(`  Warning: ${lib.file} not found at ${srcPath}, skipping.`);
+      continue;
+    }
+
+    const ext = lib.native ? path.extname(lib.file) : '.ts';
+    const destName = `${String(i).padStart(3, '0')}_${lib.name}${ext}`;
+    fs.copyFileSync(srcPath, path.join(libsDir, destName));
+    console.log(`    ${destName}`);
+    copied++;
+  }
+
+  return copied;
+}
+
+/**
+ * Resolve instance types from --instances flag.
+ * Accepts short aliases: rw, r, w (or full names).
+ * Default: single read-write instance.
+ */
+function resolveInstances(args) {
+  const instances = {};
+
+  if (args.instances && typeof args.instances === 'string') {
+    const inputs = args.instances.split(',').map(s => s.trim()).filter(Boolean);
+    const types = inputs.map(resolveInstanceType);
+    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'] = {
+      type: 'read-write',
+      deploymentId: ''
+    };
+  }
+
+  return instances;
+}
+
+function generateProjectJson(dbName, instances, envDefaults = {}, features = {}, authMode = 'noAuth') {
+  const project = {
+    name: dbName,
+    settings: {
+      loggingVerbosity: envDefaults.loggingVerbosity ?? 2
+    },
+    authMode,
+    environments: {
+      dev: {
+        driveFolderId: envDefaults.driveFolderId || '',
+        systemSpreadsheetId: '',
+        instances
+      },
+      prod: {
+        driveFolderId: '',
+        systemSpreadsheetId: '',
+        instances: {}
+      }
+    },
+  };
+
+  // Only add features block if any feature is enabled
+  if (features.rbac || features.views) {
+    project.features = {};
+    if (features.rbac) {
+      project.features.rbac = { enabled: true };
+    }
+    if (features.views) {
+      project.features.views = { enabled: true };
+    }
+  }
+
+  return JSON.stringify(project, null, 2) + '\n';
+}
+
+function generateTablesJson(tables) {
+  // Ensure every table has a spreadsheetId (default __new__ for creation)
+  const result = {};
+  for (const [name, table] of Object.entries(tables)) {
+    result[name] = {
+      spreadsheetId: '__new__',
+      ...table
+    };
+  }
+  return JSON.stringify(result, null, 2) + '\n';
+}
+
+/** RBAC system tables — injected when --rbac is used */
+const RBAC_TABLES = {
+  users: {
+    spreadsheetId: '__new__',
+    sheetName: 'users',
+    schema: {
+      id: { type: 'string', primaryKey: true, required: true },
+      email: { type: 'string', required: true },
+      name: { type: 'string', required: true },
+      role_id: { type: 'string', foreignKey: 'roles.id' },
+      role: { type: 'string' },
+      active: { type: 'boolean', defaultValue: true },
+      __audit__: { type: 'object' },
+      __archived__: { type: 'boolean', defaultValue: false }
+    },
+    idGenerator: 'UUID',
+    deleteMode: 'soft'
+  },
+  roles: {
+    spreadsheetId: '__new__',
+    sheetName: 'roles',
+    schema: {
+      id: { type: 'string', primaryKey: true, required: true },
+      name: { type: 'string', required: true },
+      description: { type: 'string' },
+      __audit__: { type: 'object' },
+      __archived__: { type: 'boolean', defaultValue: false }
+    },
+    idGenerator: 'UUID',
+    deleteMode: 'soft'
+  }
+};
+
+function generateRbacJson() {
+  return JSON.stringify({
+    roles: {
+      admin: {
+        description: 'Full access to all tables, views, and methods',
+        capabilities: ['*:*', '*']
+      },
+      publisher: {
+        description: 'Can create and edit content — no structural changes',
+        capabilities: [
+          '*:list', '*:get',
+          'pages:create', 'pages:update',
+          'entries:create', 'entries:update',
+          'categories:create', 'categories:update',
+          'tags:create', 'tags:update',
+          'media:create', 'media:update',
+          'view:*',
+          'getStats'
+        ],
+        filter: {
+          entries: 'author_id'
+        }
+      },
+      viewer: {
+        description: 'Read-only access — use views for filtered content',
+        capabilities: ['*:list', '*:get', 'view:publishedEntries', 'view:entriesByCategory']
+      }
+    },
+    defaultRole: 'viewer'
+  }, null, 2) + '\n';
+}
+
+function generateViewsJson() {
+  return JSON.stringify({}, null, 2) + '\n';
+}
+
+function generateCustomMethodsJson() {
+  return JSON.stringify({
+    getStats: {
+      handler: 'getStats.ts',
+      description: 'Example — get row counts for all tables'
+    }
+  }, null, 2) + '\n';
+}
+
+/**
+ * Scaffold the overrides/ directory with an example custom method handler.
+ */
+function scaffoldExampleOverride(overridesDir) {
+  fs.mkdirSync(overridesDir, { recursive: true });
+
+  const exampleMethod = `/**
+ * Custom method handler: getStats
+ *
+ * Convention: export a function named handle_<actionName> that receives:
+ *   - body: parsed request body
+ *   - db: DBV2 instance
+ *   - logger: logger instance
+ *   - user: (optional, if RBAC enabled) { email, role, id }
+ *
+ * Must return a GoogleAppsScript.Content.TextOutput (use jsonResponse()).
+ *
+ * Declared in customMethods.json, handler files live in overrides/.
+ * Request: POST { "action": "getStats", "apiKey": "..." }
+ */
+function handle_getStats(body: any, db: any, logger: any, user?: any): GoogleAppsScript.Content.TextOutput {
+  // Example: count rows in all tables
+  const schema = typeof DB_SCHEMA !== 'undefined' ? DB_SCHEMA : {};
+  const stats: Record<string, number> = {};
+
+  for (const tableName of Object.keys(schema)) {
+    const table = db.table(tableName);
+    if (table) {
+      const result = table.list({});
+      stats[tableName] = result?.data?.length || 0;
+    }
+  }
+
+  return jsonResponse({ stats });
+}
+`;
+  fs.writeFileSync(path.join(overridesDir, 'getStats.ts'), exampleMethod);
+}
+
+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]');
+    process.exit(1);
+  }
+
+  const dbName = args.db;
+
+  if (!/^[a-z0-9][a-z0-9_-]*$/i.test(dbName)) {
+    console.error(`Invalid DB name: "${dbName}"`);
+    console.error('Must contain only letters, numbers, hyphens, and underscores.');
+    process.exit(1);
+  }
+
+  const dbDir = path.join(DBS_DIR, dbName);
+  if (fs.existsSync(dbDir)) {
+    console.error(`DB project "${dbName}" already exists at ${dbDir}`);
+    process.exit(1);
+  }
+
+  const templates = loadTemplates();
+  let selectedTemplate;
+
+  if (args.template) {
+    selectedTemplate = templates.find(t => t.name === args.template);
+    if (!selectedTemplate) {
+      console.error(`Template "${args.template}" not found.`);
+      console.error(`Available templates: ${templates.map(t => t.name).join(', ')}`);
+      process.exit(1);
+    }
+  } else {
+    const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+
+    console.log('\nAvailable templates:\n');
+    templates.forEach((t, i) => {
+      const tableCount = Object.keys(t.tables).length;
+      console.log(`  ${i + 1}. ${t.name} — ${t.description} (${tableCount} tables)`);
+    });
+    console.log('');
+
+    const answer = await ask(rl, `Select template (1-${templates.length}): `);
+    rl.close();
+
+    const idx = parseInt(answer, 10) - 1;
+    if (isNaN(idx) || idx < 0 || idx >= templates.length) {
+      console.error('Invalid selection.');
+      process.exit(1);
+    }
+
+    selectedTemplate = templates[idx];
+  }
+
+  const instances = resolveInstances(args);
+  const envDefaults = getEnvDefaults('dev');
+
+  // Resolve auth mode
+  const VALID_AUTH_MODES = ['noAuth', 'simple', 'google'];
+  const authMode = (typeof args.auth === 'string') ? args.auth : 'noAuth';
+  if (!VALID_AUTH_MODES.includes(authMode)) {
+    console.error(`Invalid auth mode: "${authMode}". Use: ${VALID_AUTH_MODES.join(', ')}`);
+    process.exit(1);
+  }
+
+  // Resolve feature flags
+  const features = {};
+  if (args.rbac) {
+    if (authMode === 'noAuth') {
+      console.error('RBAC requires --auth simple or --auth google (cannot use noAuth with RBAC).');
+      process.exit(1);
+    }
+    features.rbac = true;
+  }
+  if (args.views) {
+    features.views = true;
+  }
+
+  // Create the DB project directory
+  fs.mkdirSync(dbDir, { recursive: true });
+
+  // Merge RBAC tables into template tables if RBAC enabled
+  let tables = { ...selectedTemplate.tables };
+  if (features.rbac) {
+    tables = { ...RBAC_TABLES, ...tables };
+  }
+
+  // Write config files
+  fs.writeFileSync(path.join(dbDir, 'project.json'), generateProjectJson(dbName, instances, envDefaults, features, authMode));
+  fs.writeFileSync(path.join(dbDir, 'tables.json'), generateTablesJson(tables));
+
+  // RBAC config
+  if (features.rbac) {
+    fs.writeFileSync(path.join(dbDir, 'rbac.json'), generateRbacJson());
+    console.log('  Created rbac.json (3 default roles: admin, publisher, viewer)');
+  }
+
+  // Views config
+  if (features.views) {
+    fs.writeFileSync(path.join(dbDir, 'views.json'), generateViewsJson());
+    console.log('  Created views.json (empty — add views after setup)');
+  }
+
+  // Custom methods config — always created with example
+  fs.writeFileSync(path.join(dbDir, 'customMethods.json'), generateCustomMethodsJson());
+  console.log('  Created customMethods.json (1 example: getStats)');
+
+  // Scaffold library files
+  const libsDir = path.join(dbDir, 'libs');
+  console.log('\n  Scaffolding libraries:');
+  const libCount = scaffoldLibs(libsDir);
+
+  // Scaffold overrides directory with example handler
+  const overridesDir = path.join(dbDir, 'overrides');
+  scaffoldExampleOverride(overridesDir);
+  console.log('\n  Scaffolding overrides:');
+  console.log('    overrides/getStats.ts (example custom method handler)');
+
+  // Register project in .nsaproject.json
+  const rootConfig = loadRootConfig();
+  if (!rootConfig.kind) rootConfig.kind = 'db';
+  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);
+
+  const tableNames = Object.keys(tables);
+  const instanceKeys = Object.keys(instances);
+  console.log(`\nCreated DB project: ${dbName}`);
+  console.log(`  Template: ${selectedTemplate.name}`);
+  console.log(`  Tables: ${tableNames.join(', ')}`);
+  console.log(`  Libs: ${libCount} files scaffolded`);
+  console.log(`  Instances: ${instanceKeys.join(', ')}`);
+  console.log(`  Auth: ${authMode}`);
+  if (features.rbac) console.log(`  RBAC: enabled`);
+  if (features.views) console.log(`  Views: enabled`);
+  console.log(`  Path: ${dbDir}`);
+  console.log(`  Registered in .nsaproject.json`);
+  console.log(`\nNext steps:`);
+  console.log(`  1. nsa-sheets-db-builder login --db ${dbName}`);
+  console.log(`  2. nsa-sheets-db-builder setup --db ${dbName}`);
+  if (features.rbac) console.log(`\n  Optional: edit dbs/${dbName}/rbac.json before setup`);
+  if (features.views) console.log(`  Optional: edit dbs/${dbName}/views.json before setup`);
+}
+
+main();