@mcpher/gas-fakes 1.1.5 → 1.1.7

package/README.md

@@ -1,110 +1,37 @@
-# A proof of concept implementation of Apps Script Environment on Node
+# <img src="./logo.png" alt="gas-fakes logo" width="50" align="top"> A proof of concept implementation of Apps Script Environment on Node
 
-I use clasp/vscode to develop Google Apps Script (GAS) applications, but when using GAS native services, there's way too much back and fowards to the GAS IDE going while testing. I set myself the ambition of implementing fake version of the GAS runtime environment on Node so I could at least do some testing and debugging of Apps Scripts locally on Node.
+I use clasp/vscode to develop Google Apps Script (GAS) applications, but when using GAS native services, there's way too much back and forwards to the GAS IDE going while testing. I set myself the ambition of implementing a fake version of the GAS runtime environment on Node so I could at least do some testing and debugging of Apps Scripts locally on Node.
 
 This is a proof of concept so I've implemented a growing subset of number of services and methods. There are a rigorous set of tests for all emulated classes and methods to make sure the same code produces the same result on both Node and Apps Script. Please report any inconsistencies in the issues of this repo.
 
 
 ## Getting started as a package user
 
-You can get the package from npm
-
+You can get the package from npm:
 ```sh
 npm i @mcpher/gas-fakes
 ```
 
-Collaborators should fork the repo and use the local versions of these files - see [collaborators info](collaborators.md).
+For a complete guide on how to set up your local environment for authentication and development, please see the consolidated guide: [Getting Started with `gas-fakes`](gas-fakes/GETTING_STARTED.md)
+
+Collaborators should fork the repo and use the local versions of these files - see collaborators info.
 
 ### Use exactly the same code as in Apps Script
 
 Just as on Apps Script, everything is executed synchronously so you don't need to bother with handling Promises/async/await. Just write normal Apps Script code. Usually you would have an associated App Script project if that's your eventual target, but it's not essential that you do. You can get started right away on Node. 
 
-
-### Cloud project
-
-You don't have access to GAS maintained cloud projects from Node, so you'll need to create a GCP project to use locally (or you can use it on Apps Script too if you prefer) that has the workspace APIs enabled (Drive, Docs, Sheets etc). 
-
-### .env and shell script helpers
-
-In order to duplicate the OAuth management handled by GAS, we'll use Application Default Credentials. I've provided a handy shell that will take care of all this for you. 
-
-- Get this [folder](https://github.com/brucemcpherson/gas-fakes/tree/main/shells) into the ./shells folder of your project.
-- Get this [env template](https://github.com/brucemcpherson/gas-fakes/blob/main/shells/.env.template) and copy it/add it to your .env file in your project
-
-#### Application default credentials
-
-In order to avoid a bunch of Node specific code and credentials, yet still handle OAuth, I figured that we could simply rely on ADC. This is a problem I already wrote about here [Application Default Credentials with Google Cloud and Workspace APIs](https://ramblings.mcpher.com/application-default-credentials-with-google-cloud-and-workspace-apis/)
-
-At the very least you need to add the gcp project id and optionally the id of some file you have access to - this'll be used to check that you have set up ADC properly.
-
-#### Your .env file
-
-You can setup the .env file your self using the .env.template as a guide.
-
-```
-# must set these
-GCP_PROJECT_ID="add your gcp project id here"
-
-# optional reference if you want to run a test after setting up
-DRIVE_TEST_FILE_ID="add the id of some test file you have access to here"
-
-# we'll use the default config for application default credentials
-# probably dont need to change these
-AC=default
-# these are the scopes set by default - take some of these out if you want to minimize access
-DEFAULT_SCOPES="https://www.googleapis.com/auth/userinfo.email,openid,https://www.googleapis.com/auth/cloud-platform"
-EXTRA_SCOPES=",https://www.googleapis.com/auth/drive,https://www.googleapis.com/auth/spreadsheets"
- 
-# optional logging destination
-# can be CONSOLE (default), CLOUD, BOTH, NONE
-LOG_DESTINATION="BOTH"
-
-```
-#### Applying the .env
-
-You can run 
-```bash
-cd shells
-bash setaccounts.sh
-```
-Which will set up and test the initial application default login with the selected scopes.
-
-#### enabling workspace services
-
-You can run this shell to enable all the required cloud services
-```bash
-cd shells
-bash enable.sh
-```
-
-#### Restricted scopes
-
-Recent changes in the OAuth security model have made it more difficult for Application Default credentials to work with all the scopes we'll need to fully emulate Live Apps Script locally. However there is a way to work around this by creating an oauth client for internal use in the cloud console, and injecting its credentials into those used by the application default creadentials process. You should now follow the guidance in [restricted scopes](restricted_scopes.md) to enhance your login process to be able access all the supported services in gas-fakes
-
-#### Manifest file
-
-If you have an associated apps script project, you'll probably be using clasp to sync with the apps script IDE, and you'll have an appsscript.json available in your project folder
-
-**gas-fakes** reads the manifest file to see which scopes you need in your project, uses the Google Auth library to attempt to authorizes them and has `ScriptApp.getOauthToken()` return a sufficiently specced token, just as the GAS environment does. Just make sure you have an `appsscript.json` in the same folder as your main script.
-
-Now you can execute this and it will set up your ADC to be able to run any services that require the scopes you add.
-
-##### note
-
-Although you may be tempted to add `https://www.googleapis.com/auth/script.external_request`, it's not necessary for the ADC and in fact will generate an error. You will of course need it in your Apps script manifest. Same goes for "https://www.googleapis.com/auth/documents" and "https://www.googleapis.com/auth/documents" 
-
 ### Settings
 
-Optionally, gasfakes.json holds various location and behavior parameters to inform about your Node environment. It's not required on GAS as you can't change anything over there. If you don't have one or need one, it'll create one for you and use some sensible defaults. Here's an example of one with the defaults. It should be in the same folder as your main script.
+The optional `gasfakes.json` file holds various location and behavior parameters for your local Node environment. It is not required on GAS, as you can't change anything over there. If you don't provide this file, `gas-fakes` will create one for you with sensible defaults.
 
-```
+```json
 {
   "manifest": "./appsscript.json",
   "clasp": "./.clasp.json",
   "documentId": null,
   "cache": "/tmp/gas-fakes/cache",
   "properties": "/tmp/gas-fakes/properties",
-  "scriptId": "1bc79bd3-fe02-425f-9653-525e5ae0b678"
+  "scriptId": "a-unique-id-for-your-local-project"
 }
 ```
 
@@ -182,7 +109,7 @@ If you want to set an initial LOG_DESTINATION using that .env file, you have to
 ```env
 node --env-file=.env yourapp.js
 ```
-Some developers prefer to use [dotenv](https://www.npmjs.com/package/dotenv) to set the path of the .env file
+Some developers prefer to use dotenv to set the path of the .env file
 ```javascript
 import dotenv from 'dotenv'
 dotenv.config({ path: '/custom/path/to/.env' })
@@ -213,11 +140,12 @@ For inspiration on pushing modified files to the IDE, see the togas.sh bash scri
 
 As I mentioned earlier, to take this further, I'm going to need a lot of help to extend the methods and services supported - so if you feel this would be useful to you, and would like to collaborate, please ping me on bruce@mcpher.com and we'll talk.
 
-## Translations and writeups
-
+## <img src="./logo.png" alt="gas-fakes logo" width="50" align="top">  Further Reading
 
+- [getting started](GETTING_STARTED.md) - how to handle authentication for restricted scopes.
+- [readme](README.md)
 - [initial idea and thoughts](https://ramblings.mcpher.com/a-proof-of-concept-implementation-of-apps-script-environment-on-node/)
-- [Inside the volatile world of a Google Document](https://ramblings.mcpher.com/inside-the-volatile-world-of-a-google-document/
+- [Inside the volatile world of a Google Document](https://ramblings.mcpher.com/inside-the-volatile-world-of-a-google-document/)
 - [Apps Script Services on Node – using apps script libraries](https://ramblings.mcpher.com/apps-script-services-on-node-using-apps-script-libraries/)
 - [Apps Script environment on Node – more services](https://ramblings.mcpher.com/apps-script-environment-on-node-more-services/)
 - [Turning async into synch on Node using workers](https://ramblings.mcpher.com/turning-async-into-synch-on-node-using-workers/)
@@ -226,8 +154,7 @@ As I mentioned earlier, to take this further, I'm going to need a lot of help to
 - [colaborators](collaborators.md) - additional information for collaborators
 - [oddities](oddities.md) - a collection of oddities uncovered during this project
 - [gemini](gemini.md) - some reflections and experiences on using gemini to help code large projects
-- [named colors](named-colors.md) - colors supported by Apps Script
-- [this file](README.md)
 - [named colors](named-colors.md)
 - [sandbox](sandbox.md)
-- [named range identity](named-range-identity.md)
+- [named range identity](named-range-identity.md)
+- [adc and restricted scopes](https://ramblings.mcpher.com/how-to-allow-access-to-sensitive-scopes-with-application-default-credentials/)

package/env.setup.template

@@ -0,0 +1,16 @@
+# for testing authentication
+GCP_PROJECT_ID="add your gcp project id here"
+
+# this is optional 
+DRIVE_TEST_FILE_ID="add the id of some test file you have access to here"
+
+# we'll use the default config for application default credentials
+AC=default
+# these are the scopes set by default - take some of these out if you want to minimize access
+DEFAULT_SCOPES="https://www.googleapis.com/auth/userinfo.email,openid,https://www.googleapis.com/auth/cloud-platform"
+EXTRA_SCOPES=",https://www.googleapis.com/auth/drive,https://www.googleapis.com/auth/spreadsheets,https://www.googleapis.com/auth/gmail.labels"
+
+# if you need access to sensitive or restricted scopes you'll need to provide a credentials file
+# this is a path relative to the project root, or an absolute path
+CLIENT_CREDENTIAL_FILE="private/gasfakes-oa.json"
+LOG_DESTINATION="CONSOLE"

package/package.json

@@ -59,13 +59,13 @@
     "testdocsfootnotes": "node ./test/testdocsfootnotes.js execute",
     "testdocsimages": "node ./test/testdocsimages.js execute",
     "testdocsstyles": "node ./test/testdocsstyles.js execute",
-    "testsandbox": "node ./test/testsandbox.js execute",
+    "testsandbox": "node --trace-warnings ./test/testsandbox.js execute",
     "testgmail": "node ./test/testgmail.js execute",
     "testlogger": "node ./test/testlogger.js execute",
     "pub": "npm publish --access public"
   },
   "name": "@mcpher/gas-fakes",
-  "version": "1.1.5",
+  "version": "1.1.7",
   "license": "MIT",
   "main": "main.js",
   "description": "A proof of concept implementation of Apps Script Environment on Node",

package/src/services/advdocs/docapis.js

@@ -5,7 +5,7 @@ import { syncLog} from '../../support/workersync/synclogger.js'
 let __client = null;
 
 export const getDocsApiClient = () => {
-  const auth = Auth.getAuth()
+  const auth = Auth.getAuthClient()
   if (!__client) {
     syncLog('Creating new Docs API client');
     __client = google.docs({ version: 'v1', auth });

package/src/services/advdrive/drapis.js

@@ -5,7 +5,7 @@ import { syncLog} from '../../support/workersync/synclogger.js'
 let __client = null;
 syncLog('...importing Drive API');
 export const getDriveApiClient = () => {
-  const auth = Auth.getAuth()
+  const auth = Auth.getAuthClient()
   if (!__client) {
     syncLog('Creating new Drive API client');
     __client = google.drive({ version: 'v3', auth });

package/src/services/advforms/formsapis.js

@@ -5,7 +5,7 @@ import { syncLog} from '../../support/workersync/synclogger.js'
 let __client = null;
 
 export const getFormsApiClient = () => {
-  const auth = Auth.getAuth()
+  const auth = Auth.getAuthClient()
   if (!__client) {
     syncLog('Creating new Forms API client');
     __client = google.forms({ version: 'v1', auth });

package/src/services/advgmail/fakeadvgmaildrafts.js

@@ -0,0 +1,31 @@
+import { FakeAdvResource } from '../common/fakeadvresource.js';
+import { Proxies } from '../../support/proxies.js';
+import { gError, normalizeSerialization } from '../../support/helpers.js';
+import { Syncit } from '../../support/syncit.js';
+
+export const newFakeAdvGmailDrafts = (...args) => Proxies.guard(new FakeAdvGmailDrafts(...args));
+
+class FakeAdvGmailDrafts extends FakeAdvResource {
+  constructor(mainService) {
+    super(mainService, 'users', Syncit.fxGmail);
+    this.gmail = mainService;
+    this.__fakeObjectType = 'Gmail.Users.Drafts';
+  }
+
+  /**
+   * Creates a new draft with the DRAFT label.
+   * @param {object} resource - The draft resource to create.
+   * @param {string} userId - The user's email address. The special value me can be used to indicate the authenticated user.
+   * @returns {object} The created draft resource.
+   */
+  create(resource, userId) {
+    const { data, response } = this._call(
+      'create',
+      { userId, requestBody: normalizeSerialization(resource) },
+      null,
+      'drafts'
+    );
+    gError(response, 'gmail', 'users.drafts.create');
+    return data;
+  }
+}

package/src/services/advgmail/fakeadvgmailusers.js

@@ -2,6 +2,7 @@ import { FakeAdvResource } from '../common/fakeadvresource.js';
 import { Syncit } from '../../support/syncit.js';
 import { signatureArgs, ssError, gError } from '../../support/helpers.js';
 import { newFakeAdvGmailLabels } from './fakeadvgmaillabels.js';
+import { newFakeAdvGmailDrafts } from './fakeadvgmaildrafts.js';
 
 import { Proxies } from '../../support/proxies.js';
 import { Utils } from '../../support/utils.js';
@@ -20,4 +21,8 @@ class FakeAdvGmailUsers extends FakeAdvResource {
     return newFakeAdvGmailLabels(this.gmail);
   }
 
+  get Drafts() {
+    return newFakeAdvGmailDrafts(this.gmail);
+  }
+
 }

package/src/services/advgmail/gmailapis.js

@@ -5,7 +5,7 @@ import { syncLog} from '../../support/workersync/synclogger.js'
 let __client = null;
 
 export const getGmailApiClient = () => {
-  const auth = Auth.getAuth()
+  const auth = Auth.getAuthClient()
   if (!__client) {
     syncLog('Creating new Gmail API client');
     __client = google.gmail({ version: 'v1', auth });

package/src/services/advsheets/shapis.js

@@ -5,7 +5,7 @@ let currentAuth = null;
 let __client = null;
 syncLog('...importing Sheets API');
 export const getSheetsApiClient = () => {
-  const auth = Auth.getAuth()
+  const auth = Auth.getAuthClient()
 
   if (__client && currentAuth !== auth) {
     syncLog('Auth has changed - creating new Sheets API client');

package/src/services/advslides/slapis.js

@@ -6,7 +6,7 @@ import { syncLog} from '../../support/workersync/synclogger.js'
 let __client = null;
 syncLog('...importing Slides API');
 export const getSlidesApiClient = () => {
-  const auth = Auth.getAuth()
+  const auth = Auth.getAuthClient()
   if (!__client) {
     syncLog('Creating new Slides API client');
     __client = google.slides({ version: 'v1', auth });

package/src/services/gmailapp/fakegmailapp.js

@@ -1,5 +1,6 @@
 import { Proxies } from '../../support/proxies.js';
 import { newFakeGmailLabel } from './fakegmaillabel.js';
+import { newFakeGmailDraft } from './fakegmaildraft.js';
 
 /**
  * Provides access to Gmail threads, messages, and labels.
@@ -9,6 +10,31 @@ class FakeGmailApp {
     this.__fakeObjectType = 'GmailApp';
   }
 
+  /**
+   * Creates a draft email message.
+   * @param {string} recipient a comma-separated list of email addresses
+   * @param {string} subject the subject of the message
+   * @param {string} body the body of the message
+   * @returns {GmailDraft} the newly created draft
+   */
+  createDraft(recipient, subject, body) {
+    // this is a fairly naive implementation of rfc2822
+    const raw = [
+      `To: ${recipient}`,
+      `Subject: ${subject}`,
+      'Content-Type: text/plain; charset=utf-8',
+      '',
+      body,
+    ].join('\r\n');
+
+    // rfc4648 url safe alphabet
+    const encoded = Utilities.base64Encode(raw, Utilities.Charset.UTF_8)
+      .replace(/\+/g, '-').replace(/\//g, '_');
+
+    const draft = Gmail.Users.Drafts.create({ message: { raw: encoded } }, 'me');
+    return newFakeGmailDraft(draft);
+  }
+
   /**
    * Creates a new user label.
    * @param {string} name The name of the new label.

package/src/services/gmailapp/fakegmaildraft.js

@@ -0,0 +1,30 @@
+import { Proxies } from '../../support/proxies.js';
+
+export const newFakeGmailDraft = (...args) => Proxies.guard(new FakeGmailDraft(...args));
+
+/**
+ * A draft email message in a user's Gmail account.
+ * @see https://developers.google.com/apps-script/reference/gmail/gmail-draft
+ */
+class FakeGmailDraft {
+  constructor(draftResource) {
+    this.__draftResource = draftResource;
+    this.__fakeObjectType = 'GmailDraft';
+  }
+
+  /**
+   * Gets the ID of this draft.
+   * @returns {string} The draft ID.
+   */
+  getId() {
+    return this.__draftResource.id;
+  }
+
+  /**
+   * Returns "GmailDraft"
+   * @returns {string}
+   */
+  toString() {
+    return this.__fakeObjectType;
+  }
+}

package/src/support/auth.js

@@ -9,7 +9,6 @@ const _authScopes = new Set([])
 let _auth = null
 let _projectId = null
 let _tokenInfo = null
-let _adcPath = null
 let _accessToken = null;
 let _tokenExpiresAt = null;
 let _manifest = null
@@ -24,8 +23,6 @@ const getSettings = () => _settings
 const getScriptId = () => getSettings().scriptId
 const getDocumentId = () => getSettings().documentId
 const setProjectId = (projectId) => _projectId = projectId
-const setAdcPath = (adcPath) => _adcPath = adcPath
-const getAdcPath = () => _adcPath
 const setAccessToken = (accessToken) => _accessToken = accessToken
 const setSettings = (settings) => _settings = settings
 const getCachePath = () => getSettings().cache
@@ -61,30 +58,29 @@ const isTokenExpired = () => !_accessToken || !_tokenExpiresAt || Date.now() >=
  * @param {string[]} [scopes=[]] the required scopes will be added to existing scopes already asked for
  * @returns {GoogleAuth.auth}
  */
-
+let _authClient = null
+const getAuthClient = () => _authClient
 const setAuth = async (scopes = [], keyFile = null) => {
-  if (!hasAuth() || !scopes.every(s => _authScopes.has(s))) {
-    syncLog(`...initializing auth and discovering project ID`);
-    // First auth is just to get the project ID.
-    const initialAuth = new GoogleAuth({
-      keyFile,
-      scopes: ['https://www.googleapis.com/auth/cloud-platform'], // Minimal scope
-    });
-
-    // Discover and cache the project ID. This also serves as validation.
-    _projectId = await initialAuth.getProjectId();
+  const hasCurrentAuth = hasAuth() && scopes.every(s => _authScopes.has(s));
+  
+  
+  if (!hasCurrentAuth) {
+    syncLog(`...initializing auth and discovering project ID`); 
+    
+    // 1. Create the GoogleAuth manager instance (this instance has getProjectId)
+    _auth = new GoogleAuth({ scopes });
+    
+    // 2. Use the manager to get the authenticated client (this is passed to API methods)
+    _authClient = await _auth.getClient();
+    
+    // 3. Use the manager to reliably get the project ID
+    _projectId = await _auth.getProjectId();
+    
     if (!_projectId) {
       throw new Error('Failed to get project ID from Application Default Credentials.');
     }
+    
     syncLog(`...discovered and set projectId to ${_projectId}`);
-
-    // Now, create the *real* auth client with the projectId and all required scopes.
-    _auth = new GoogleAuth({
-      keyFile,
-      scopes,
-      projectId: _projectId,
-    });
-
     scopes.forEach(s => _authScopes.add(s));
   }
   return getAuth();
@@ -184,8 +180,6 @@ export const Auth = {
   getAuthedScopes,
   googify,
   setProjectId,
-  setAdcPath,
-  getAdcPath,
   getUserId,
   setTokenInfo,
   getAccessToken,
@@ -203,5 +197,6 @@ export const Auth = {
   getClasp,
   getTimeZone,
   setAccessToken,
-  isTokenExpired
+  isTokenExpired,
+  getAuthClient
 }

package/src/support/sxauth.js

@@ -7,7 +7,7 @@
  */
 import got from 'got';
 import { Auth } from './auth.js';
-import { syncLog } from './workersync/synclogger.js';
+import { syncError, syncLog } from './workersync/synclogger.js';
 import { homedir } from 'os';
 import {access, readFile, writeFile, mkdir } from 'fs/promises';
 import path from 'path'
@@ -28,35 +28,8 @@ import path from 'path'
  */
 export const sxInit = async ({ manifestPath, claspPath, settingsPath, mainDir, cachePath, propertiesPath, fakeId }) => {
 
-  const findAdcPath = async () => {
 
 
-    if (process.env.GOOGLE_APPLICATION_CREDENTIALS) {
-      return process.env.GOOGLE_APPLICATION_CREDENTIALS;
-    }
-    const isWindows = process.platform === 'win32';
-    const home = homedir();
-    let adcPath;
-    if (isWindows) {
-      const appData = process.env.APPDATA;
-      if (appData) {
-        adcPath = path.join(appData, 'gcloud', 'application_default_credentials.json');
-      }
-    } else {
-      adcPath = path.join(home, '.config', 'gcloud', 'application_default_credentials.json');
-    }
-
-    if (adcPath) {
-      try {
-        await access(adcPath);
-        return adcPath;
-      } catch {
-        // file doesn't exist or not accessible
-      }
-    }
-    return null;
-  };
-
   // get the settings and manifest
 
 
@@ -118,17 +91,19 @@ export const sxInit = async ({ manifestPath, claspPath, settingsPath, mainDir, c
   // Initialize auth. This is async and will discover the project ID.
   const auth = await Auth.setAuth(scopes);
   const projectId = Auth.getProjectId();
-  const adcPath = await findAdcPath();
   const accessToken = await auth.getAccessToken()
-  const tokenInfo = await got(`https://www.googleapis.com/oauth2/v3/tokeninfo?access_token=${accessToken}`).json()
-
+  let tokenInfo = null
+  try {
+    tokenInfo = await got(`https://www.googleapis.com/oauth2/v3/tokeninfo?access_token=${accessToken}`).json()
+  } catch (err) {
+    syncError (`failed to get access token info`)
+  }
 
   /// these all jst exist in this sub process so we need to send them back to parent process
   return {
     scopes,
     projectId,
     tokenInfo,
-    adcPath,
     accessToken, // also return the token itself
     settings,
     manifest,

package/src/support/sxdrive.js

@@ -11,6 +11,8 @@ import intoStream from 'into-stream';
 import { getStreamAsBuffer } from 'get-stream';
 import { syncWarn, syncError } from './workersync/synclogger.js';
 import { getDriveApiClient } from '../services/advdrive/drapis.js';
+
+
 /**
  * serializable reponse from a sync call
  * @typedef SxResponse

package/src/support/syncit.js

@@ -284,7 +284,6 @@ const fxInit = ({
     scopes,
     projectId,
     tokenInfo,
-    adcPath,
     accessToken,
     settings,
     manifest,
@@ -295,7 +294,6 @@ const fxInit = ({
   Auth.setProjectId(projectId);
   //Auth.setAuth(scopes)
   Auth.setTokenInfo(tokenInfo);
-  Auth.setAdcPath(adcPath)
   //Auth.setAccessToken(accessToken)
   Auth.setSettings(settings);
   Auth.setClasp(clasp);

package/src/support/workersync/synchronizer.js

@@ -6,12 +6,42 @@ import fs from 'node:fs';
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = path.dirname(__filename);
 
+// --- Start: Suppress google-auth-library warnings globally ---
+// A regex to match either of the Google Auth deprecation warnings.
+const googleAuthWarningRegex = /The `from(Stream|JSON)` method is deprecated/;
+
+// Monkey-patch the main process's write methods to filter output.
+const patchStream = (stream) => {
+  const originalWrite = stream.write;
+  stream.write = (chunk, encoding, callback) => {
+    const message = typeof chunk === 'string' ? chunk : chunk.toString();
+    if (googleAuthWarningRegex.test(message)) {
+      // If it's a warning we want to suppress, do nothing.
+      return true;
+    }
+    // Otherwise, call the original write method.
+    return originalWrite.apply(stream, [chunk, encoding, callback]);
+  };
+};
+
+patchStream(process.stdout);
+patchStream(process.stderr);
+// --- End: Suppress google-auth-library warnings ---
+
+// Define indices for the control buffer to avoid magic numbers.
+const CONTROL_INDICES = {
+  STATUS: 0,      // 0: free, 1: busy, 2: worker_init
+  DATA_SIZE: 1,   // Size of the result data in bytes
+  IS_ERROR: 2,    // 0: success, 1: error
+  RESULT_TYPE: 3, // 0: buffer, 1: file
+};
+
 // Shared buffer for control signals
 // [0]: status lock (0: free, 1: busy, 2: worker_init)
 // [1]: result data size in bytes
 // [2]: error flag (0: success, 1: error)
 // [3]: result type (0: buffer, 1: file)
-const controlBuf = new SharedArrayBuffer(Int32Array.BYTES_PER_ELEMENT * 4);
+const controlBuf = new SharedArrayBuffer(Int32Array.BYTES_PER_ELEMENT * Object.keys(CONTROL_INDICES).length);
 const control = new Int32Array(controlBuf);
 
 // Shared buffer for data transfer (e.g., 16MB)
@@ -24,7 +54,7 @@ const textDecoder = new TextDecoder();
 // The single, long-lived worker
 const worker = new Worker(path.resolve(__dirname, 'worker.js'));
 
-// Pipe worker's stdout and stderr to the main process to see its logs
+// Pipe worker's output directly. The patch above will handle filtering.
 worker.stdout.pipe(process.stdout);
 worker.stderr.pipe(process.stderr);
 
@@ -33,7 +63,7 @@ worker.stderr.pipe(process.stderr);
 worker.on('error', (error) => {
   console.error('Worker thread encountered a fatal error:', error);
   // Unblock any pending Atomics.wait() call to prevent a deadlock.
-  Atomics.store(control, 0, 0); // Set status to "free"
+  Atomics.store(control, CONTROL_INDICES.STATUS, 0); // Set status to "free"
   Atomics.notify(control, 0);
   // Exit the main process, as the application is in an unrecoverable state.
   process.exit(1);
@@ -44,24 +74,33 @@ worker.on('exit', (code) => {
   // This handles cases where the worker exits unexpectedly.
   if (code !== 0) {
     console.error(`Worker thread stopped with exit code ${code}`);
-    Atomics.store(control, 0, 0); // Unblock main thread
+    Atomics.store(control, CONTROL_INDICES.STATUS, 0); // Unblock main thread
     Atomics.notify(control, 0);
   }
 });
 
 // Send the shared buffers to the worker once and wait for it to confirm initialization
-Atomics.store(control, 0, 2); // Set status to "worker_init"
+Atomics.store(control, CONTROL_INDICES.STATUS, 2); // Set status to "worker_init"
 worker.postMessage({ controlBuf, dataBuf });
-Atomics.wait(control, 0, 2); // Wait for worker to set status to "free" (0)
+Atomics.wait(control, CONTROL_INDICES.STATUS, 2); // Wait for worker to set status to "free" (0)
 
 // Allow the main process to exit even if the worker is still running.
 worker.unref();
 
-// Ensure worker is terminated when the main process exits
-process.on('exit', () => {
-  console.log ('...worker is terminating')
-  worker.terminate()
-});
+/**
+ * Ensures the worker is terminated when the main process exits,
+ * whether normally or via signals like Ctrl+C.
+ */
+function cleanup() {
+  console.log('...terminating worker thread');
+  worker.terminate();
+}
+
+// The 'exit' event is for when the process is already shutting down normally.
+process.on('exit', cleanup);
+// By not listening for 'SIGINT', we allow Node.js to perform its default action,
+// which is to exit the process. The 'exit' event will then be fired to clean up the worker.
+process.on('SIGTERM', cleanup); // Catches `kill`
 
 /**
  * Calls an async function in the worker and blocks until it returns.
@@ -74,7 +113,7 @@ export function callSync(method, ...args) {
 
 
   // 1. Set status to "busy". This acts as a lock.
-  Atomics.store(control, 0, 1);
+  Atomics.store(control, CONTROL_INDICES.STATUS, 1);
 
   // 2. Send the task to the worker.
   const payload = { method, args };
@@ -83,12 +122,12 @@ export function callSync(method, ...args) {
   // 3. Block and wait for the worker to finish.
   // It's "busy" (1) until the worker sets it back to "free" (0).
   // This is a true blocking wait, consuming minimal CPU.
-  Atomics.wait(control, 0, 1);
+  Atomics.wait(control, CONTROL_INDICES.STATUS, 1);
 
   // 4. Worker is done, result is in the shared buffer.
-  const resultSize = Atomics.load(control, 1);
-  const hasError = Atomics.load(control, 2) === 1;
-  const resultIsFile = Atomics.load(control, 3) === 1;
+  const resultSize = Atomics.load(control, CONTROL_INDICES.DATA_SIZE);
+  const hasError = Atomics.load(control, CONTROL_INDICES.IS_ERROR) === 1;
+  const resultIsFile = Atomics.load(control, CONTROL_INDICES.RESULT_TYPE) === 1;
 
   if (resultSize > dataBuf.byteLength) {
     throw new Error(

package/src/support/workersync/worker.js

@@ -10,6 +10,14 @@ let control;
 let dataView;
 const textEncoder = new TextEncoder();
 
+// Define indices for the control buffer to match synchronizer.js
+const CONTROL_INDICES = {
+  STATUS: 0,      // 0: free, 1: busy, 2: worker_init
+  DATA_SIZE: 1,   // Size of the result data in bytes
+  IS_ERROR: 2,    // 0: success, 1: error
+  RESULT_TYPE: 3, // 0: buffer, 1: file
+};
+
 /**
  * Writes a result to the shared buffer and sets control flags.
  * @param {*} result The successful result to write.
@@ -27,16 +35,16 @@ async function writeResult(result) {
 
     // Write the path to the shared buffer
     dataView.set(pathBytes);
-    Atomics.store(control, 1, pathBytes.length); // data size (of the path)
-    Atomics.store(control, 2, 0); // success flag
-    Atomics.store(control, 3, 1); // result type: file
+    Atomics.store(control, CONTROL_INDICES.DATA_SIZE, pathBytes.length); // data size (of the path)
+    Atomics.store(control, CONTROL_INDICES.IS_ERROR, 0); // success flag
+    Atomics.store(control, CONTROL_INDICES.RESULT_TYPE, 1); // result type: file
   } else {
     // Result fits in the buffer, write it directly.
 
     dataView.set(encodedResult);
-    Atomics.store(control, 1, encodedResult.length); // data size
-    Atomics.store(control, 2, 0); // success flag
-    Atomics.store(control, 3, 0); // result type: buffer
+    Atomics.store(control, CONTROL_INDICES.DATA_SIZE, encodedResult.length); // data size
+    Atomics.store(control, CONTROL_INDICES.IS_ERROR, 0); // success flag
+    Atomics.store(control, CONTROL_INDICES.RESULT_TYPE, 0); // result type: buffer
  
   }
 }
@@ -55,9 +63,9 @@ function writeError(error) {
   const encodedError = textEncoder.encode(errorString);
 
   dataView.set(encodedError);
-  Atomics.store(control, 1, encodedError.length); // data size
-  Atomics.store(control, 2, 1); // error flag
-  Atomics.store(control, 3, 0); // result type: buffer (errors are always small enough)
+  Atomics.store(control, CONTROL_INDICES.DATA_SIZE, encodedError.length); // data size
+  Atomics.store(control, CONTROL_INDICES.IS_ERROR, 1); // error flag
+  Atomics.store(control, CONTROL_INDICES.RESULT_TYPE, 0); // result type: buffer (errors are always small enough)
 }
 
 // 1. Receive the shared buffers from the main thread on startup.
@@ -66,7 +74,7 @@ parentPort.once('message', (msg) => {
   dataView = new Uint8Array(msg.dataBuf);
 
   // Signal that the worker is ready.
-  Atomics.store(control, 0, 0);
+  Atomics.store(control, CONTROL_INDICES.STATUS, 0);
   Atomics.notify(control, 0);
 });
 
@@ -79,7 +87,9 @@ const handleUncaughtError = (error) => {
   // If control is not initialized, we can't report the error.
   // Just log it and exit.
   if (control) {
-    syncError('A fatal, unhandled error occurred in the worker', error);
+    // Log the full error stack to identify the call site
+    syncError('A fatal, unhandled error occurred in the worker. The worker will be unresponsive.', error);
+
     writeError(error);
     Atomics.notify(control, 0);
   }
@@ -105,8 +115,7 @@ parentPort.on('message', async (task) => {
       // sxInit is special: it creates the auth state and returns serializable info.
       result = await asyncFn(...task.args);
 
-      // Configure the worker's persistent Auth object.
-      Auth.setAdcPath(result.adcPath);
+
       // The projectId is already discovered and set within the initial `sxInit` -> `setAuth` call.
       // This subsequent call is redundant, so it is removed for clarity.
       // Auth.setProjectId(result.projectId);
@@ -132,7 +141,7 @@ parentPort.on('message', async (task) => {
     writeError(error);
   } finally {
     // 3. Signal completion and wake up the main thread.
-    Atomics.store(control, 0, 0);
+    Atomics.store(control, CONTROL_INDICES.STATUS, 0);
     Atomics.notify(control, 0);
   }
 });