nsa-sheets-db-builder 4.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 NoStackApps
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,188 @@
+# sheets-deployer
+
+DDL provisioner for Google Sheets — treats spreadsheets as databases with tables, schemas, and migrations.
+
+## What it does
+
+- Creates Google Drive folders and spreadsheets as database containers
+- Provisions tables (sheets) with typed column headers from a schema definition
+- Builds and pushes Google Apps Script code via clasp
+- Per-project Google account credentials with environment isolation
+- Configurable library bundling (logger, error handler, response helper)
+- Schema drift detection and sync
+
+## Install
+
+```bash
+npm install -g sheets-deployer
+# or
+npx sheets-deployer <command>
+```
+
+### Requirements
+
+- Node.js >= 18
+- [@google/clasp](https://github.com/google/clasp) >= 2.4.0
+
+## Quick start
+
+```bash
+# 1. Init a new project from a template
+sheets-deployer init --db my-shop --template e-commerce
+
+# 2. Set your GAS script ID in dbs/my-shop/db.config.json
+
+# 3. Login (stores creds per project)
+sheets-deployer login --db my-shop
+
+# 4. Build + push to Google Apps Script
+sheets-deployer push --db my-shop
+
+# 5. Create Drive folder + spreadsheets
+sheets-deployer create --db my-shop
+
+# 6. Provision tables from schema
+sheets-deployer provision --db my-shop
+```
+
+## Commands
+
+| Command | Description |
+|---------|-------------|
+| `init` | Initialize a new DB project from a template |
+| `build` | Build GAS output for a DB project |
+| `push` | Build + push to Google Apps Script |
+| `deploy` | Build + push + deploy as web app |
+| `clean` | Clean build output |
+| `create` | Create Drive folder + system/data spreadsheets |
+| `provision` | Provision tables from schema.ts |
+| `show` | List tables in data spreadsheet |
+| `describe` | Describe a table's columns |
+| `drop` | Drop a table |
+| `sync` | Detect drift between schema and live sheets |
+| `status` | Show tables with status info |
+| `set-key` | Set the DDL API key |
+| `rotate-key` | Generate + set a random API key |
+| `refresh-cache` | Refresh the `__sys__tables__` cache |
+| `setup-trigger` | Set up time-based cache refresh trigger |
+| `remove-trigger` | Remove cache refresh trigger |
+| `login` | Login to Google for a DB project |
+| `whoami` | Check current Google account |
+
+All commands accept `--db <name>` and most accept `--env <env>` (defaults to `dev`).
+
+## Templates
+
+Start from a pre-built schema:
+
+| Template | Tables | Use case |
+|----------|--------|----------|
+| `blank` | 1 | Minimal starter |
+| `blog-cms` | 8 | Content management (posts, categories, tags, media) |
+| `crm` | — | Customer relationship management |
+| `e-commerce` | — | Products, orders, customers |
+| `inventory` | — | Stock tracking |
+
+```bash
+sheets-deployer init --db my-app --template blog-cms
+sheets-deployer init --db my-app --template blank --minimal   # core libs only
+sheets-deployer init --db my-app --template crm --libs gaslogger,gaserror  # pick specific libs
+```
+
+## Authentication
+
+Each DB project can have its own Google account credentials, preventing accidental pushes to the wrong environment.
+
+```bash
+# Login stores creds in dbs/<name>/.clasprc.json
+sheets-deployer login --db my-app
+
+# Check who's logged in
+sheets-deployer whoami --db my-app
+
+# Use global ~/.clasprc.json instead
+sheets-deployer push --db my-app --inherit
+
+# Skip account validation
+sheets-deployer push --db my-app --force
+```
+
+Account enforcement: if `db.config.json` has an `account` field per environment, push/deploy will block on mismatch.
+
+## Project structure
+
+```
+dbs/
+  my-app/
+    db.config.json     # Project config (scriptId, env settings, lib selection)
+    schema.ts          # Table definitions
+    .clasprc.json      # Per-project Google credentials (gitignored)
+dist/
+  my-app/              # Built GAS output (gitignored)
+```
+
+### db.config.json
+
+```json
+{
+  "name": "my-app",
+  "libs": ["gaslogger", "gaserror", "gas_response_helper", "spreadsheets_db", "db_ddl"],
+  "settings": { "loggingVerbosity": 2 },
+  "environments": {
+    "dev": {
+      "scriptId": "YOUR_SCRIPT_ID",
+      "account": "dev@gmail.com",
+      "driveFolderId": "",
+      "systemSpreadsheetId": "",
+      "spreadsheetIds": [],
+      "deploymentId": ""
+    },
+    "prod": { ... }
+  },
+  "activeEnv": "dev"
+}
+```
+
+## Libraries
+
+The build bundles libraries into numbered `.gs` files for Google Apps Script.
+
+**Core** (always required):
+- `spreadsheets_db` — Database abstraction layer for Google Sheets
+- `db_ddl` — Schema provisioning (DDL) operations
+
+**Optional** (from [gas-common-libs](../common)):
+- `gaslogger` — Structured logging with verbosity levels
+- `gaserror` — Error wrapping with context, trace IDs, and stack chains
+- `gas_response_helper` — Standardized API response formatting
+
+Use `--minimal` to skip optional libs, or `--libs` to pick specific ones.
+
+## Environment defaults
+
+Create `.env.dev` or `.env.prod` at the project root for shared defaults:
+
+```bash
+DEFAULT_ACCOUNT=dev@gmail.com
+DRIVE_ROOT_FOLDER_ID=1abc...
+DEFAULT_LOGGING_VERBOSITY=2
+```
+
+These are used as fallbacks when initializing new DB projects.
+
+## Build pipeline
+
+The build concatenates everything into numbered `.gs` files:
+
+```
+000-098  Library dependencies (from libs/ and common/)
+099      Config template (env, scriptId, logging level)
+100      Schema bundle (schema.ts → stripped of TS types)
+101+     API source files (src/api/*.ts → stripped of TS + imports)
+```
+
+Plus `appsscript.json` and `.clasp.json` manifests.
+
+## License
+
+MIT

package/bin/sheets-deployer.mjs

@@ -0,0 +1,169 @@
+#!/usr/bin/env node
+
+/**
+ * CLI dispatcher for nsa-sheets-db-builder.
+ *
+ * Usage:
+ *   nsa-sheets-db-builder <command> [options]
+ *   npx nsa-sheets-db-builder <command> [options]
+ *
+ * Commands:
+ *   init             Initialize a new DB project from a template
+ *   build            Build GAS output for a DB project
+ *   push             Build + push to Google Apps Script
+ *   deploy           Build + push + deploy
+ *   clean            Clean build output
+ *   create           Create Drive folder + spreadsheets
+ *   provision        Provision tables from schema
+ *   show             Show tables in data spreadsheet
+ *   describe         Describe a table's columns
+ *   drop             Drop a table
+ *   sync             Sync schema — detect drift
+ *   status           Show tables + status info
+ *   set-key          Set DDL API key
+ *   rotate-key       Generate + set random API key
+ *   refresh-cache    Refresh __sys__tables__ cache
+ *   setup-trigger    Set up cache refresh trigger
+ *   remove-trigger   Remove cache refresh trigger
+ *   login            Login to Google for a DB project
+ *   whoami           Check current Google account
+ *   setup            Full first-time setup (create → build → deploy)
+ *   ddl-handler      Build, push, deploy the shared DDL handler
+ *
+ * Global options:
+ *   --db <name>        DB project name (required for most commands)
+ *   --env <env>        Target environment (default: activeEnv from config)
+ *   --instance <name>  Target instance (auto-selected if only one exists)
+ *   --force            Skip account validation
+ *   --inherit          Use default clasp credentials
+ */
+
+import { execSync } from 'child_process';
+import path from 'path';
+import { fileURLToPath } from 'url';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const scriptsDir = path.resolve(__dirname, '..', 'scripts');
+
+// Command → script mapping
+const COMMANDS = {
+  'init':            'init.mjs',
+  'build':           'build.mjs',
+  'push':            ['build.mjs', '--push'],
+  'deploy':          ['build.mjs', '--push', '--deploy'],
+  'clean':           'clean.mjs',
+  'create':          'create.mjs',
+  'provision':       'provision.mjs',
+  'show':            'show.mjs',
+  'describe':        'describe.mjs',
+  'drop':            'drop.mjs',
+  'sync':            'sync.mjs',
+  'status':          ['show.mjs', '--status'],
+  'set-key':         'set-key.mjs',
+  'rotate-key':      ['set-key.mjs', '--rotate'],
+  'refresh-cache':   'refresh-cache.mjs',
+  'setup-trigger':   'setup-trigger.mjs',
+  'remove-trigger':  ['setup-trigger.mjs', '--remove'],
+  'login':           'login.mjs',
+  'whoami':          'whoami.mjs',
+  'setup':           'setup.mjs',
+  'ddl-handler':     'ddl-handler.mjs'
+};
+
+const command = process.argv[2];
+const restArgs = process.argv.slice(3);
+
+if (!command || command === '--help' || command === '-h') {
+  console.log('nsa-sheets-db-builder v4.0.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));
+  for (const cmd of Object.keys(COMMANDS)) {
+    console.log(`  ${cmd.padEnd(maxLen + 2)} ${getDescription(cmd)}`);
+  }
+  console.log('\nGlobal options:');
+  console.log('  --db <name>        DB project name (required for most commands)');
+  console.log('  --env <env>        Target environment (default: activeEnv from config)');
+  console.log('  --instance <type>  Target instance: rw, r, w (or full name / scriptId)');
+  console.log('  --force            Skip account validation');
+  console.log('  --inherit          Use default clasp credentials');
+  console.log('\nInstance type aliases:');
+  console.log('  rw = read-write    Full CRUD + locking');
+  console.log('  r  = read-only     Read operations only, no locking');
+  console.log('  w  = write-only    Write operations only');
+  console.log('\nFeature flags (init only):');
+  console.log('  --rbac <mode>      Enable RBAC (mode: request | workspace)');
+  console.log('  --views            Enable SQL views support');
+  console.log('\nProject layout:');
+  console.log('  dbs/<name>/project.json        Project config (all-in-one)');
+  console.log('  dbs/<name>/tables.json         Table definitions (schema)');
+  console.log('  dbs/<name>/customMethods.json  Custom method declarations');
+  console.log('  dbs/<name>/libs/               Library source files (.ts)');
+  console.log('  dbs/<name>/overrides/          Custom method handler files (.ts)');
+  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');
+  console.log('  nsa-sheets-db-builder init --db my-app --instances r,w');
+  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');
+  console.log('  nsa-sheets-db-builder deploy --db my-app --instance r');
+  process.exit(0);
+}
+
+if (!COMMANDS[command]) {
+  console.error(`Unknown command: "${command}"`);
+  console.error(`Run "nsa-sheets-db-builder --help" for available commands.`);
+  process.exit(1);
+}
+
+// Resolve script + any built-in args
+const mapping = COMMANDS[command];
+const scriptFile = Array.isArray(mapping) ? mapping[0] : mapping;
+const builtinArgs = Array.isArray(mapping) ? mapping.slice(1) : [];
+
+const scriptPath = path.join(scriptsDir, scriptFile);
+const allArgs = [...builtinArgs, ...restArgs];
+
+// Set PROJECT_ROOT to cwd so dbs/ and dist/ resolve relative to user's directory
+const env = {
+  ...process.env,
+  NSA_SHEETS_DB_BUILDER_ROOT: process.cwd()
+};
+
+try {
+  execSync(`node "${scriptPath}" ${allArgs.map(a => `"${a}"`).join(' ')}`, {
+    stdio: 'inherit',
+    env
+  });
+} catch {
+  process.exit(1);
+}
+
+function getDescription(cmd) {
+  const descriptions = {
+    'init': 'Initialize a new DB project from a template',
+    'build': 'Build GAS output for a DB project (all instances)',
+    'push': 'Build + push instance to Google Apps Script',
+    'deploy': 'Build + push + deploy instance',
+    'clean': 'Clean build output',
+    'create': 'Create Drive folder + spreadsheets',
+    'provision': 'Provision tables from schema',
+    'show': 'Show tables in data spreadsheet',
+    'describe': 'Describe a table\'s columns',
+    'drop': 'Drop a table',
+    'sync': 'Sync schema — detect drift',
+    'status': 'Show tables + status info',
+    'set-key': 'Set DDL API key (per instance)',
+    'rotate-key': 'Generate + set random API key (per instance)',
+    'refresh-cache': 'Refresh __sys__tables__ cache',
+    'setup-trigger': 'Set up cache refresh trigger',
+    'remove-trigger': 'Remove cache refresh trigger',
+    'login': 'Login to Google for a DB project',
+    'whoami': 'Check current Google account',
+    'setup': 'Full first-time setup: create GAS projects, build, push, deploy',
+    'ddl-handler': 'Build, push, deploy the shared DDL handler'
+  };
+  return descriptions[cmd] || '';
+}