@suffolklitlab/alkiln 5.13.2 → 5.13.3-feat-random

package/lib/docassemble/docassemble_api_interface.js

@@ -1,5 +1,5 @@
 const _da_REST = require('./docassemble_api_REST');
-const log = require('../utils/log');
+const Log = require('../utils/Log');
 const session_vars = require('../utils/session_vars' );
 const time = require('../utils/time');
 
@@ -61,6 +61,10 @@ const time = require('../utils/time');
 let da_i = {};
 module.exports = da_i;
 
+const context = `da api`;
+const artifacts_path = session_vars.get_artifacts_path_name();
+const log = new Log({ path: artifacts_path, context });
+
 
 // Constants
 const DEFAULT_MAX_REQUEST_MS = session_vars.get_setup_timeout_ms();
@@ -92,7 +96,9 @@ da_i.throw_an_error_if_server_is_not_responding = async function ( options ) {
 
   // Defaults
   let { timeout } = options || { timeout: DEFAULT_MAX_REQUEST_MS };
-  log.info({ type: `da api`, code: `ALK0166`, pre: `Waiting for the docassemble server to respond. Will wait for ${ timeout/1000 } seconds at most.` });
+  log.info({ code: `ALK0166`, context, },
+    `Waiting for the docassemble server to respond. Will wait for ${ timeout/1000 } seconds at most.`
+  );
   
   try {
     let start_time = Date.now()
@@ -100,7 +106,9 @@ da_i.throw_an_error_if_server_is_not_responding = async function ( options ) {
     let response = await _da_REST.get_dev_id( timeout );
     let end_time = Date.now()
     if ( response && response.data && response.data.id ) {
-      log.info({ type: `da api`, code: `ALK0167`, pre: `The docassemble server responded after ${ (end_time - start_time)/1000 } seconds.` });
+      log.info({ code: `ALK0167`, context, },
+        `The docassemble server responded after ${ (end_time - start_time)/1000 } seconds.`
+      );
       return false;
     }
 
@@ -109,17 +117,16 @@ da_i.throw_an_error_if_server_is_not_responding = async function ( options ) {
     if ( is_timeout_error( error ) ) {
       // Anything that's waiting for the server to not be busy does not want
       // to move forward without a free server.
-      log.info({ type: `da api`, code: `ALK0168`, pre: `The docassemble server was still busy after ${ timeout/1000 } seconds.` });
+      log.info({ code: `ALK0168`, context, },
+        `The docassemble server was still busy after ${ timeout/1000 } seconds.`
+      );
     } else {
       // Not sure what to do for other errors. It could be a server
       // error, like an 'Access Denied' error, which should be handled.
-      log.error({
-        type: `da api`,
-        code: `ALK0169`,
-        pre: `Tried to check if the docassemble server was busy, but `
-        + `ran into an unexpected error. The error didn't indicate a busy server, though. Error message:\n`
-        + error
-      });
+      log.warning({ code: `ALK0169`, context, },
+        `Checked if the server was busy and ran into a different error`,
+        error
+      );
     }
 
     throw error;
@@ -187,7 +194,7 @@ da_i.get_api_key_access_status = async function ({ timeout = null, api_key = nul
   *    to allow for server request.
   */
 
-  let auth_data = {
+  let auth_feedback = {
     codes: [ 1 ],
     has_auth: null,
     messages: [`API key authorization is not yet determined.`],
@@ -196,16 +203,16 @@ da_i.get_api_key_access_status = async function ({ timeout = null, api_key = nul
 
   // Skip this for tests run from ALKilnInThePlayground
   if ( session_vars.get_origin() === 'playground' ) {
-    auth_data.codes.push( 2 );
-    auth_data.messages.push( `API keys are unnecessary for tests run in the Playground.` );
+    auth_feedback.codes.push( 2 );
+    auth_feedback.messages.push( `API keys are unnecessary for tests run in the Playground.` );
   }
 
   if ( typeof api_key !== `string` ) {
-    auth_data.codes.push( 3 );
-    auth_data.messages.push( `The given API key is not a string. Type: ${ typeof api_key }`);
+    auth_feedback.codes.push( 3 );
+    auth_feedback.messages.push( `The given API key is not a string. Type: ${ typeof api_key }`);
   }
 
-  if ( auth_data.codes.length === 1 ) {
+  if ( auth_feedback.codes.length === 1 ) {
     // Default timeouts
     timeout = timeout || DEFAULT_MAX_REQUEST_MS;
     try {
@@ -213,29 +220,31 @@ da_i.get_api_key_access_status = async function ({ timeout = null, api_key = nul
         api_key,
         server_url: session_vars.get_da_server_url(),
       });
-      auth_data.has_auth = true;
-      auth_data.codes = [ 6 ];
-      auth_data.messages = [ `This API key has at least basic authorization on this server.` ];
+      auth_feedback.has_auth = true;
+      auth_feedback.codes = [ 6 ];
+      auth_feedback.messages = [ `This API key has at least basic authorization on this server.` ];
 
     } catch ( error ) {
-      auth_data.error = error;
+      auth_feedback.error = error;
       if ( error.status === 403 ) {
-        auth_data.has_auth = false;
-        auth_data.codes = [ 4 ];
-        auth_data.messages = [ `This API is unverified on this server. It is probably missing or has been deleted.` ];
+        auth_feedback.has_auth = false;
+        auth_feedback.codes = [ 4 ];
+        auth_feedback.messages = [ `This API is unverified on this server. It is probably missing or has been deleted.` ];
       } else {
         // Note on 404, non-existent key: 404 == 403 - Since we're using the
         // key itself to get its own info, if it doesn't exist, we'll get 403
-        auth_data.codes = [ 5 ];
-        auth_data.messages = [ `This API key threw a non-403 error.` ];
+        auth_feedback.codes = [ 5 ];
+        auth_feedback.messages = [ `This API key threw a non-403 error.` ];
       }  // ends error status
     }  // ends try
-  }  // ends auth_data.codes only has the first code
+  }  // ends auth_feedback.codes only has the first code
 
-  log.debug({ type: `da api info`, code: `ALK0202`,
-    pre: `API key authentication info`, data: auth_data });
+  log.debug({ code: `ALK0202`, context, },
+    `API key - what happened during authentication:`,
+    auth_feedback
+  );
 
-  return auth_data;
+  return auth_feedback;
 };  // Ends da_i.get_api_key_access_status()
 
 // node -e 'require("./lib/docassemble/docassemble_api_interface.js").delete_project( "create1" )'
@@ -247,16 +256,19 @@ da_i.delete_project = async function ( delete_options ) {
   let { timeout } = delete_options || { timeout: DEFAULT_MAX_REQUEST_MS };
 
   let project_name = session_vars.get_project_name()
-  log.info({ type: `da api`, code: `ALK0170`, pre: `Trying to delete Project ${ project_name }` });
+  log.info({ code: `ALK0170`, context, },
+    `Trying to delete Project ${ project_name }`
+  );
 
   try {
     let response = await _da_REST.delete_project( timeout );
-    log.info({ type: `da api`, code: `ALK0171`, pre: `Deleted Project "${ project_name }"` });
+    log.info({ code: `ALK0171`, context, },
+      `Deleted Project "${ project_name }"`
+    );
   } catch ( error ) {
-    let msg = `Ran into an error when deleting Project "${ project_name }". See https://docassemble.org/docs/api.html#playground_delete_project.`
-    log.error({ type: `da api`, code: `ALK0172`, pre: msg });
-    log.debug({ type: `da api`, code: `ALK0173`, pre: msg });
-    throw error;
+    log.throw({ code: `ALK0172`, context, error: error },
+      `Ran into an error when deleting Project "${ project_name }". See https://docassemble.org/docs/api.html#playground_delete_project.`
+    );
   }
 
 };  // Ends da_i.delete_project()
@@ -280,7 +292,9 @@ da_i.quietly_try_to_delete_interviews = async function ({ interviews = {}, api_k
       });
       responses.push( sub_responses );
     } else {
-      log.debug({ type: `da api info`, code: `ALK0191`, pre: `There is no interview to delete.` });
+      log.debug({ code: `ALK0191`, context, },
+        `There is no interview to delete.`
+      );
     }
   }
   return responses;
@@ -295,9 +309,9 @@ da_i.quietly_delete_one_interview = async function ( timeout, { interview = {},
   let responses = [];
   for ( let api_key of api_keys ) {
     try {
-      log.debug({ type: `da api info`, code: `ALK0188`,
-        pre: `Trying to delete the interview with the id ${ interview.uid } and an API key.`
-      });
+      log.debug({ code: `ALK0188`, context, },
+        `Trying to delete the interview with the id ${ interview.uid } and an API key.`
+      );
 
       // Actual work:
       let response = await _da_REST.delete_interview( timeout, {
@@ -306,13 +320,15 @@ da_i.quietly_delete_one_interview = async function ( timeout, { interview = {},
       });
       responses.push( response );
 
-      log.debug({ type: `da api info`, code: `ALK0189`,
-        pre: `No error when trying to delete interview ${ interview.uid } at ${ interview.i }.`
-      });
+      log.debug({ code: `ALK0189`, context, },
+        `No error when trying to delete interview ${ interview.uid } at ${ interview.i }.`
+      );
     } catch ( error ) {
       error.interview = interview;
-      let msg = `Error when deleting the interview. See https://docassemble.org/docs/api.html#session_delete.`
-      log.debug({ type: `da api info`, code: `ALK0190`, pre: msg, data: error });
+      log.debug({ code: `ALK0190`, context, },
+        `Error when deleting the interview. See https://docassemble.org/docs/api.html#session_delete.`,
+        error
+      );
     }
   }  // ends for api keys
   return responses;
@@ -347,7 +363,9 @@ da_i.get_interview = async function ({ interview = {}, api_keys = [], options =
   if ( interview && interview.uid ) {
     for ( let api_key of api_keys ) {
       try {
-        log.debug({ type: `da api info`, code: `ALK0192`, pre: `Trying to get the interview with the id ${ interview.uid } and an API key.` });
+        log.debug({ code: `ALK0192`, context, },
+          `Trying to get the interview with the id ${ interview.uid } and an API key.`
+        );
 
         // Actual work:
         let response = await _da_REST.get_interview( timeout, {
@@ -356,20 +374,28 @@ da_i.get_interview = async function ({ interview = {}, api_keys = [], options =
         });
 
         if ( response && response.data && response.data.items && response.data.items[0] && response.data.items[0].session ) {
-          log.debug({ type: `da api info`, code: `ALK0193`, pre: `Status ${ response.status }. Got ${ response.data.items[0].session }.`});
+          log.debug({ code: `ALK0193`, context, },
+            `Status ${ response.status }. Got ${ response.data.items[0].session }.`
+          );
           return response.data.items[0];
         } else {
-          log.debug({ type: `da api info`, code: `ALK0194`, pre: `Status ${ response.status }. Cannot find ${ interview.uid }`});
+          log.debug({ code: `ALK0194`, context, },
+            `Status ${ response.status }. Cannot find ${ interview.uid }`
+          );
         }
 
       } catch ( error ) {
         error.interview = interview;
-        let msg = `${ error.status || `No error.status.` } ${ error.statusText || error.data || `No error.statusText.` } Ran into an error when getting the interview ${ interview.uid }. See https://docassemble.org/docs/api.html#interviews.`
-        log.debug({ type: `da api info`, code: `ALK0195`, pre: msg, data: error });
+        log.debug({ code: `ALK0195`, context, },
+          `${ error.status || `No error.status.` } ${ error.statusText || error.data || `No error.statusText.` } Ran into an error when getting the interview ${ interview.uid }. See https://docassemble.org/docs/api.html#interviews.`,
+          error
+        );
       }
     }  // ends for api_keys
   } else {
-    log.debug({ type: `da api info`, code: `ALK0196`, pre: `There is no interview to get.` });
+    log.debug({ code: `ALK0196`, context, },
+      `There is no interview to get.`
+    );
   }
 
   return null;

package/lib/docassemble/server_install.js

@@ -1,10 +1,20 @@
 #!/usr/bin/env node
 
 const session_vars = require('../utils/session_vars');
-const log = require('../utils/log');
+const Log = require('../utils/Log');
 const fg = require('fast-glob');
 
+const context = `server_install`;
+
 const server_install = async () => {
+  /** For packages we are installing on a temporary GitHub docassemble server.
+   *
+   *  - Store that the package is being installed globally on a server as
+   *    opposed to on a specific author's account (their Playground).
+   *  - In the repo, find and store the path to directory that stores the
+   *    package itself instead of the whole repo. For example, EvictionDefense
+   *    in the docassemble-EvictionDefense repo.
+   * */
   session_vars.save_install_method(`server`);
 
   // Get path to folders inside repo main "docassemble" folder
@@ -23,20 +33,33 @@ const server_install = async () => {
   // Get names of all folders in repo "docassemble" folder
   let chosen_folder = folders[0];
   if ( folders.length === 0 ) {
-    let msg = `There are 0 folders at ${path}. Stopping tests.`;
-    log.error({ type: `setup`, code: `ALK0044`, data: msg })
-    throw new ReferenceError( msg );
+    let msg = `ALKiln cannot find the package's files. There are 0 folders at "${ path }". Stopping tests.`;
+    log.throw({ code: `ALK0044`, context,
+      error: new ReferenceError( msg )  // no logs
+    });
   }
 
   if ( folders.length > 1 ) {
-    log.warn({
-      type: `setup`,
-      code: `ALK0045`,
-      data: `There are ${folders.length} folders at ${path}: "${folders.join('", "')}". ALKiln chose to use the folder "${chosen_folder}".`
-    })
+    log.warn({ code: `ALK0045`, context, },
+      `There are ${ folders.length } folders at "${ path }": "${ folders.join('", "') }". ALKiln chose to use the folder "${ chosen_folder }".`
+    );
+  } else {
+    log.info({ code: `ALK0218`, context, },
+      `ALKiln found the package folder at "${ chosen_folder }".`
+    );
   }
   
   session_vars.save_repo_folder_name( chosen_folder );
 };  // Ends server_install();
 
+// 1. session_vars - make sure all the required env vars exist
+session_vars.validateEnvironment();
+
+// 2. Prepare logs
+// Local devs: This will be separate from your test paths
+// unless you pass a `path` argument into the cucumber run command
+const argv = require(`minimist`)(process.argv.slice(2));
+const log = new Log({ path: argv.path, context, });
+
+// 3. run
 server_install();

package/lib/docassemble/setup.js

@@ -1,26 +1,35 @@
 #!/usr/bin/env node
 
-// TODO: Rename to playground_install?
+// rename? install_authors_docassemble_interview_package_on_server
 
 const child_process = require(`child_process`);
 
-const log = require(`../utils/log`);
+const Log = require(`../utils/Log`);
 const session_vars = require(`../utils/session_vars` );
+const files = require(`../utils/files` );
+const time = require(`../utils/time` );
+
+const context = `setup`;
 
 const setup = async () => {
-  /** In the docassemble testing account identified by the
-  *   DOCASSEMBLE_DEVELOPER_API_KEY secret, create a new Project,
-  *   pull code into that project, and, if needed, wait for the
-  *   server to reload.
-  */
+  /** This is for a package being installed in an author's account (Playground)
+   *  on their docassemble server. Using the author's
+   *   DOCASSEMBLE_DEVELOPER_API_KEY secret, create a new Project, pull code
+   *   into that project, and, if needed, wait for the server to reload.
+   */
   
   // Make and save project name
   let project_name = session_vars.get_project_base_name().replace(/[^A-Za-z0-9]/g, '') + `${Date.now()}`;
   session_vars.save_project_name( project_name );
 
-  log.info({ type: `setup`, code: `ALK0046`, pre: `Starting to upload this package to `
+  const starting_msg = `Starting to upload this package to `
     + `a new Project called ${project_name} in the Playground `
-    + `of your server's testing account. It may take a couple of minutes.` });
+    + `of your server's testing account. It may take a couple of minutes.`;
+  log.info({ code: `ALK0046`, context, },
+    starting_msg
+  );
+
+  // TODO: 1. Start listening to the normal console here (for debug logging)
 
   // dainstall . --apiurl https://site.org --apikey $API_KEY --playground --project=name
   // I think this won't run on windows? Why do I think this? Where on the
@@ -34,29 +43,37 @@ const setup = async () => {
       `--playground`, `--project=${ project_name }`
     ],
     // Prints messages from the process to the console while it's running
+    // result.stderr, result.stdout, etc. will be `null`
     { stdio: 'inherit', }
   );
 
-  // 403 is invalid API key, but I'm not sure how to output
-  // the response to find out the error code
+  // TODO: 2. Stop listening to the normal console here
 
+  // 403 is invalid API key, but I'm not sure how to output
+  // the response to find out the error code. stderr is `null`.
   if ( result.status !== 0 ) {
-    log.error({
-      type: `setup`,
-      code: `ALK0047`,
-      pre: `Status code ${ result.status }. Could not dainstall this package on your server. See above for more details.`
-    });
-    throw(result.stderr);
+    const install_err_msg = `Status code ${ result.status }. Could not `
+      + `dainstall this package on your server. See above for more details.`;
+    log.throw({ code: `ALK0047`, context,
+      before: `☝️ ☝️ ☝️  Error data ☝️ ☝️ ☝️\n`,
+      error: `Error while installing project` },
+      install_err_msg
+    );
   }
 
-  log.success({
-    type: `setup`,
-    code: `ALK0048`,
-    pre: `ALKiln created a Project in your Playground named "${ project_name }"!`
-  });
+  log.success({ code: `ALK0048`, context, },
+    `ALKiln created a Project in your Playground named "${ project_name }"!`
+  );
 };  // Ends setup();
 
-
-// Before everything, make sure all the required env vars exist
+// 1. session_vars - make sure all the required env vars exist
 session_vars.validateEnvironment();
+
+// 2. Prepare logs
+// Local devs: This will be separate from your test paths unless you pass a
+//    `path` argument into the cucumber run command
+const argv = require(`minimist`)(process.argv.slice(2));
+const log = new Log({ path: argv.path, context, });
+
+// 3. run
 setup();

package/lib/docassemble/takedown.js

@@ -1,26 +1,49 @@
 #!/usr/bin/env node
 
 const da_i = require('./docassemble_api_interface');
-const log = require('../utils/log');
-const session_vars = require('../utils/session_vars' );
+const session_vars = require('../utils/session_vars');
+const Log = require('../utils/Log');
+
+const context = `takedown`;
 
 const takedown = async () => {
-  /* In the docassemble testing account identified by the
-  *   DOCASSEMBLE_DEVELOPER_API_KEY secret, delete the
-  *   Project created for this test.
-  *   For local development, clean up project name file. */
-  log.info({ type: `takedown`, code: `ALK0177`, pre: `Trying to remove the docassemble Project from the testing account.` });
+  /** In the docassemble testing account identified by the
+   *  DOCASSEMBLE_DEVELOPER_API_KEY secret, delete the Project created for this
+   *  test. For local development, clean up Project name in the runtime_config
+   *  file.
+   * */
+  log.info({ code: `ALK0177`, context, },
+    `Trying to remove the docassemble Project from the testing account.`
+  );
   // Explicit try-catch prevents "Unhandled promise rejection error"
   // avoids showing confusing node errors to users that they shouldn't have to fix
   try {
     await da_i.delete_project();
     session_vars.delete_project_name();
-    log.success({ type: `takedown`, code: `ALK0178`, pre: `Test takedown has finished successfully!` });
+    log.info({ code: `ALK0178`, context, },
+      `Test takedown finished successfully!`
+    );
   } catch (error) {
-    log.error({type: `takedown`, code: `ALK0179`, pre: `Could not delete project`, data: JSON.stringify(error, null, 4)})
-    // we don't re-throw the exception, so make sure to exit with 1 to let GitHub Actions know the script failed
+    log.throw({ code: `ALK0179`, context, error: error },
+      `Unable to delete project`,
+    );
+    // we don't re-throw the exception, so make sure to exit
+    // with 1 to let GitHub Actions know the script failed
     process.exitCode = 1;
   }
+
+  // TODO: ? Build the final setup, run, & takedown verbose log
+  // file in here. Add to it in the GitHub action ?
 };
 
+// 1. session_vars - make sure all the required env vars exist
+session_vars.validateEnvironment();
+
+// 2. Prepare logs
+// Local devs: This will be separate from your test artifacts paths unless you
+//    pass a `path` argument into the `cucumber` run command
+const argv = require(`minimist`)( process.argv.slice(2) );
+const log = new Log({ path: argv.path, context, });
+
+// 3. run
 takedown();

package/lib/globals.js

@@ -0,0 +1,10 @@
+let globals = {
+  // File name prefix ALKiln can use to identify random answer generator files
+  generators_prefix: `alkiln_random`,
+  generated_files_folder_name: `_alkiln_generated`,
+}
+
+module.exports = globals;
+
+// Would this be clearer as a config file instead?
+// If not, change name to `constants`?