gas-digital-twin 1.0.0

package/README.md

@@ -0,0 +1,184 @@
+# gas-digital-twin
+
+Test Google Apps Script locally. Zero dependencies.
+
+14 in-memory mocks of GAS APIs — SpreadsheetApp, GmailApp, DriveApp, HtmlService, ScriptApp, and more — so you can run `.gs` files in Node.js with real test assertions.
+
+## Quick Start
+
+```bash
+npm install gas-digital-twin
+```
+
+```js
+import { setup, teardown, SpreadsheetApp, loadGsFile } from 'gas-digital-twin';
+
+// Set up mock environment with fixture data
+setup({
+  spreadsheets: {
+    'sheet-123': {
+      name: 'My Sheet',
+      sheets: {
+        'Data': [['Name', 'Score'], ['Alice', 95], ['Bob', 87]]
+      }
+    }
+  }
+});
+
+// Load and run a .gs file
+const { exports: gs } = loadGsFile('./my-script.gs');
+gs.processData();
+
+// Assert against mock state
+const sheet = SpreadsheetApp.openById('sheet-123').getSheetByName('Data');
+assert.equal(sheet.getRange(1, 2).getValue(), 'Score');
+
+teardown();
+```
+
+## Multi-File Projects
+
+Real GAS projects have multiple `.gs` files sharing a global scope. gas-digital-twin handles this:
+
+```js
+import { setup, teardown, loadGsProject } from 'gas-digital-twin';
+
+setup({ /* fixtures */ });
+
+// Load all .gs files in a directory — shared scope, just like GAS
+const { exports: gs } = loadGsProject('./gas/');
+gs.anyFunctionFromAnyFile();
+
+teardown();
+```
+
+## CLI
+
+```bash
+# Run a function from a .gs file
+gas-twin run script.gs myFunction
+
+# Run a function from a project directory
+gas-twin run ./gas/ myFunction --fixture data.json
+
+# Watch mode — rerun on file changes
+gas-twin run script.gs myFunction --watch
+
+# List all functions in a file or project
+gas-twin list ./gas/
+
+# Generate a test skeleton
+gas-twin init ./gas/ > tests/test-project.js
+```
+
+## Fixture Files
+
+Load test data from JSON:
+
+```json
+{
+  "spreadsheets": {
+    "sheet-id": {
+      "name": "Test Sheet",
+      "sheets": { "Sheet1": [["Header"], ["Value"]] }
+    }
+  },
+  "threads": [
+    { "from": "sender@example.com", "subject": "Hello", "body": "World" }
+  ],
+  "folders": [
+    { "id": "folder-1", "name": "Documents" }
+  ],
+  "documents": { "doc-1": "Document text content" },
+  "htmlFiles": { "sidebar": "<div>HTML</div>" },
+  "calendars": {
+    "cal-1": {
+      "name": "Work",
+      "events": [{ "title": "Standup", "startTime": "2026-04-04T09:00:00", "endTime": "2026-04-04T09:30:00" }]
+    }
+  },
+  "activeUser": "user@example.com"
+}
+```
+
+Thread shorthand: `{ from, subject, body }` auto-wraps into a single-message thread.
+
+## Snapshot Testing
+
+Compare spreadsheet state against stored snapshots:
+
+```js
+import { assertSnapshot } from 'gas-digital-twin';
+
+// First run: writes the snapshot file
+// Subsequent runs: compares and throws on mismatch
+assertSnapshot(import.meta.url, sheet, 'after-processing');
+
+// Force update a snapshot
+assertSnapshot(import.meta.url, sheet, 'after-processing', { update: true });
+```
+
+Works with spreadsheets, individual sheets, Logger output, or any JSON-serializable value.
+
+## Available Mocks
+
+| Mock | Key Methods |
+|------|-------------|
+| **SpreadsheetApp** | `openById`, `getActiveSpreadsheet`, `flush`, `getUi` |
+| **GmailApp** | `search` (from:, label:, -label:, keywords), `sendEmail`, `getInboxThreads` |
+| **DriveApp** | `getFolderById`, `getFileById`, `createFolder`, `createFile`, folder traversal |
+| **UrlFetchApp** | `fetch` with registered URL responses |
+| **DocumentApp** | `openById`, `getBody().getText()` |
+| **Drive** (Advanced) | `Files.insert` (OCR bridge to DocumentApp), `Files.trash` |
+| **HtmlService** | `createHtmlOutput`, `createHtmlOutputFromFile`, `createTemplate`, enums |
+| **ScriptApp** | `newTrigger` (builder chain), `getProjectTriggers`, `deleteTrigger`, `getService` |
+| **MailApp** | `sendEmail` (positional + object), `getRemainingDailyQuota` |
+| **CalendarApp** | `getDefaultCalendar`, `createEvent`, `getEvents` (date range), `deleteEvent` |
+| **Logger** | `log`, `getLog`, `clear` |
+| **Utilities** | `formatDate`, `base64Encode/Decode`, `newBlob`, `getUuid` |
+| **PropertiesService** | `getScriptProperties`, `getUserProperties`, `getDocumentProperties` |
+| **Session** | `getActiveUser`, `getEffectiveUser` |
+
+Every mock follows the same pattern: module-level state, `_addX()` helpers for setup, `_reset()` for teardown.
+
+## CI Integration
+
+```bash
+# JUnit XML for GitHub Actions
+npm run test:junit > results.xml
+
+# Coverage (built into Node 20+)
+npm run test:coverage
+
+# Watch mode for TDD
+npm run test:watch
+```
+
+## Capture Fixtures from Live Sheets
+
+```bash
+# With googleapis installed
+gas-twin-capture <spreadsheet-id> -o fixtures/data.json
+
+# From piped JSON (works with any data source)
+echo '{"Sheet1": [["A","B"],[1,2]]}' | gas-twin-capture --stdin -o fixtures/data.json
+```
+
+## Inline Editor
+
+Split-screen terminal editor with live test feedback:
+
+```bash
+gas-twin-edit script.gs myFunction --fixture data.json
+```
+
+Ctrl+S saves and reruns, Ctrl+Z undo, Ctrl+Q quit.
+
+## Requirements
+
+- Node.js >= 20.0.0
+- Zero npm dependencies
+
+## License
+
+MIT

package/bin/gas-capture.js

@@ -0,0 +1,181 @@
+#!/usr/bin/env node
+
+/**
+ * GAS Digital Twin — Fixture Capture
+ *
+ * Reads a live Google Spreadsheet and outputs fixture JSON.
+ * Requires GOOGLE_APPLICATION_CREDENTIALS or gcloud auth.
+ *
+ * Usage:
+ *   gas-twin capture <spreadsheet-id> [-o output.json] [--sheets Sheet1,Sheet2]
+ *
+ * This uses the Google Sheets API directly (no MCP dependency).
+ * Auth: uses Application Default Credentials or a service account key.
+ *
+ * If no Google credentials are available, it can also accept piped JSON:
+ *   echo '{"Sheet1": [["A","B"],[1,2]]}' | gas-twin capture --stdin -o fixture.json
+ */
+
+import { writeFileSync } from 'node:fs';
+import { resolve } from 'node:path';
+
+const HELP = `
+gas-twin capture — Generate fixture JSON from a live Google Spreadsheet
+
+Usage:
+  gas-twin capture <spreadsheet-id> [-o output.json] [--sheets Sheet1,Sheet2]
+  gas-twin capture --stdin [-o output.json]
+
+Options:
+  -o, --output    Write to file instead of stdout
+  --sheets        Comma-separated list of sheet names to capture (default: all)
+  --stdin         Read sheet data as JSON from stdin
+  --help, -h      Show this help
+
+Examples:
+  gas-twin capture 1oCMqgT4lzUg78Fdh-L-XNRAmckxZgN0tLGjxrFaWres
+  gas-twin capture 1oCMqgT4... -o fixtures/invoice-tracker.json --sheets Invoices,Counters
+`;
+
+async function main() {
+  const args = process.argv.slice(2);
+
+  if (args.length === 0 || args.includes('--help') || args.includes('-h')) {
+    console.log(HELP);
+    process.exit(0);
+  }
+
+  // Parse args
+  const outputIdx = Math.max(args.indexOf('-o'), args.indexOf('--output'));
+  const outputFile = outputIdx >= 0 ? args[outputIdx + 1] : null;
+
+  const sheetsIdx = args.indexOf('--sheets');
+  const sheetFilter = sheetsIdx >= 0 ? args[sheetsIdx + 1].split(',') : null;
+
+  if (args.includes('--stdin')) {
+    await captureFromStdin(outputFile, sheetFilter);
+    return;
+  }
+
+  const spreadsheetId = args.find(a => !a.startsWith('-') && a !== outputFile && (sheetsIdx < 0 || a !== args[sheetsIdx + 1]));
+
+  if (!spreadsheetId) {
+    console.error('Error: spreadsheet ID required');
+    process.exit(1);
+  }
+
+  await captureFromApi(spreadsheetId, outputFile, sheetFilter);
+}
+
+async function captureFromApi(spreadsheetId, outputFile, sheetFilter) {
+  // Try to use Google Sheets API via googleapis
+  let sheets;
+  try {
+    const { google } = await import('googleapis');
+    const auth = new google.auth.GoogleAuth({
+      scopes: ['https://www.googleapis.com/auth/spreadsheets.readonly'],
+    });
+    sheets = google.sheets({ version: 'v4', auth });
+  } catch {
+    // googleapis not available — provide instructions
+    console.error('Google Sheets API not available.');
+    console.error('');
+    console.error('Options:');
+    console.error('  1. Install googleapis: npm install googleapis');
+    console.error('  2. Use MCP: Use the Google Sheets MCP to read the sheet,');
+    console.error('     then pipe the data: echo \'{"Sheet1": [...]}\' | gas-twin capture --stdin');
+    console.error('  3. Use the manual approach: copy sheet data to JSON manually');
+    console.error('');
+    console.error('For MCP users (Claude Code):');
+    console.error(`  Read the spreadsheet with sheets_read_range, then format as fixture JSON.`);
+    process.exit(1);
+  }
+
+  try {
+    // Get spreadsheet metadata
+    const meta = await sheets.spreadsheets.get({ spreadsheetId });
+    const name = meta.data.properties.title;
+    const allSheets = meta.data.sheets.map(s => s.properties.title);
+    const targetSheets = sheetFilter || allSheets;
+
+    console.error(`Capturing: "${name}" (${targetSheets.length} sheets)`);
+
+    // Read each sheet
+    const sheetData = {};
+    for (const sheetName of targetSheets) {
+      console.error(`  Reading: ${sheetName}...`);
+      const res = await sheets.spreadsheets.values.get({
+        spreadsheetId,
+        range: sheetName,
+      });
+      sheetData[sheetName] = res.data.values || [];
+    }
+
+    const fixture = {
+      spreadsheets: {
+        [spreadsheetId]: {
+          name,
+          sheets: sheetData,
+        },
+      },
+    };
+
+    outputFixture(fixture, outputFile);
+  } catch (e) {
+    console.error(`Error: ${e.message}`);
+    process.exit(1);
+  }
+}
+
+async function captureFromStdin(outputFile, sheetFilter) {
+  const chunks = [];
+  for await (const chunk of process.stdin) {
+    chunks.push(chunk);
+  }
+
+  const raw = Buffer.concat(chunks).toString('utf-8');
+  let data;
+  try {
+    data = JSON.parse(raw);
+  } catch {
+    console.error('Error: invalid JSON on stdin');
+    process.exit(1);
+  }
+
+  // If data is already in fixture format, pass through
+  if (data.spreadsheets) {
+    outputFixture(data, outputFile);
+    return;
+  }
+
+  // Otherwise, assume it's { "SheetName": [[row], [row]] } format
+  const sheets = {};
+  for (const [name, rows] of Object.entries(data)) {
+    if (sheetFilter && !sheetFilter.includes(name)) continue;
+    sheets[name] = rows;
+  }
+
+  const fixture = {
+    spreadsheets: {
+      'captured-sheet': {
+        name: 'Captured Sheet',
+        sheets,
+      },
+    },
+  };
+
+  outputFixture(fixture, outputFile);
+}
+
+function outputFixture(fixture, outputFile) {
+  const json = JSON.stringify(fixture, null, 2) + '\n';
+
+  if (outputFile) {
+    writeFileSync(resolve(outputFile), json);
+    console.error(`Written to ${outputFile}`);
+  } else {
+    process.stdout.write(json);
+  }
+}
+
+main();