cht-conf 4.2.0 → 4.4.0

package/CHANGELOG.md

@@ -1,3 +1,17 @@
+# [4.4.0](https://github.com/medic/cht-conf/compare/v4.3.0...v4.4.0) (2024-12-16)
+
+
+### Features
+
+* **#650:** delete-contacts action ([#652](https://github.com/medic/cht-conf/issues/652)) ([129f38f](https://github.com/medic/cht-conf/commit/129f38fca83fa84717c7ba16857b315c25d33b9e)), closes [#650](https://github.com/medic/cht-conf/issues/650)
+
+# [4.3.0](https://github.com/medic/cht-conf/compare/v4.2.0...v4.3.0) (2024-12-16)
+
+
+### Features
+
+* **#648:** add --disable-users command for merge-contacts action ([#649](https://github.com/medic/cht-conf/issues/649)) ([c78d3fd](https://github.com/medic/cht-conf/commit/c78d3fd1ed1588cfefdf21384840743f5faea62d)), closes [#648](https://github.com/medic/cht-conf/issues/648)
+
 # [4.2.0](https://github.com/medic/cht-conf/compare/v4.1.3...v4.2.0) (2024-12-11)
 
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cht-conf",
-  "version": "4.2.0",
+  "version": "4.4.0",
   "description": "Configure CHT deployments",
   "main": "./src/lib/main.js",
   "engines": {

package/src/fn/delete-contacts.js

@@ -0,0 +1,64 @@
+const minimist = require('minimist');
+const path = require('path');
+
+const environment = require('../lib/environment');
+const pouch = require('../lib/db');
+const { info } = require('../lib/log');
+
+const HierarchyOperations = require('../lib/hierarchy-operations');
+
+module.exports = {
+  requiresInstance: true,
+  execute: () => {
+    const args = parseExtraArgs(environment.pathToProject, environment.extraArgs);
+    const db = pouch();
+    const options = {
+      docDirectoryPath: args.docDirectoryPath,
+      force: args.force,
+      disableUsers: args.disableUsers,
+    };
+    return HierarchyOperations(db, options).delete(args.sourceIds);
+  }
+};
+
+// Parses extraArgs and asserts if required parameters are not present
+const parseExtraArgs = (projectDir, extraArgs = []) => {
+  const args = minimist(extraArgs, { boolean: true });
+
+  const sourceIds = (args.contacts || args.contact || '')
+    .split(',')
+    .filter(id => id);
+
+  if (sourceIds.length === 0) {
+    usage();
+    throw Error('Action "delete-contacts" is missing required list of contacts to be deleted');
+  }
+
+  return {
+    sourceIds,
+    disableUsers: !!args['disable-users'],
+    docDirectoryPath: path.resolve(projectDir, args.docDirectoryPath || 'json_docs'),
+    force: !!args.force,
+  };
+};
+
+const bold = text => `\x1b[1m${text}\x1b[0m`;
+const usage = () => {
+  info(`
+${bold('cht-conf\'s delete-contacts action')}
+When combined with 'upload-docs' this action recursively deletes a contact and all of their descendant contacts and data. ${bold('This operation is permanent. It cannot be undone.')}
+
+${bold('USAGE')}
+cht --local delete-contacts -- --contacts=<id1>,<id2>
+
+${bold('OPTIONS')}
+--contacts=<id1>,<id2>  (or --contact=<id1>,<id2>)
+  A comma delimited list of ids of contacts to be deleted.
+
+--disable-users
+  When flag is present, users at any deleted place will be permanently disabled.
+
+--docDirectoryPath=<path to stage docs>
+  Specifies the folder used to store the documents representing the changes in hierarchy.
+`);
+};

package/src/fn/merge-contacts.js

@@ -13,6 +13,7 @@ module.exports = {
     const args = parseExtraArgs(environment.pathToProject, environment.extraArgs);
     const db = pouch();
     const options = {
+      disableUsers: args.disableUsers,
       docDirectoryPath: args.docDirectoryPath,
       force: args.force,
     };
@@ -41,6 +42,7 @@ const parseExtraArgs = (projectDir, extraArgs = []) => {
   return {
     destinationId: args.destination,
     sourceIds,
+    disableUsers: !!args['disable-users'],
     docDirectoryPath: path.resolve(projectDir, args.docDirectoryPath || 'json_docs'),
     force: !!args.force,
   };
@@ -63,6 +65,9 @@ ${bold('OPTIONS')}
 --sources=<source_id1>,<source_id2>
   A comma delimited list of IDs of contacts which will be deleted. The hierarchy of contacts and reports under it will be moved to be under the destination contact.
 
+--disable-users
+  When flag is present, users at any deleted place will be updated and may be permanently disabled. Supported by CHT Core 4.7 and above.
+
 --docDirectoryPath=<path to stage docs>
   Specifies the folder used to store the documents representing the changes in hierarchy.
 `);

package/src/fn/upload-docs.js

@@ -1,19 +1,22 @@
 const path = require('path');
 const minimist = require('minimist');
-const userPrompt = require('../lib/user-prompt');
+const semver = require('semver');
 
+const api = require('../lib/api');
 const environment = require('../lib/environment');
 const fs = require('../lib/sync-fs');
+const { getValidApiVersion } = require('../lib/get-api-version');
 const log = require('../lib/log');
 const pouch = require('../lib/db');
 const progressBar = require('../lib/progress-bar');
+const userPrompt = require('../lib/user-prompt');
 
 const { info, trace, warn } = log;
 
 const FILE_EXTENSION = '.doc.json';
 const INITIAL_BATCH_SIZE = 100;
 
-const execute = async () => {
+async function execute() {
   const args = minimist(environment.extraArgs || [], { boolean: true });
 
   const docDir = path.resolve(environment.pathToProject, args.docDirectoryPath || 'json_docs');
@@ -22,22 +25,23 @@ const execute = async () => {
     return Promise.resolve();
   }
 
-  const filesToUpload = fs.recurseFiles(docDir).filter(name => name.endsWith(FILE_EXTENSION));
-  const docIdErrors = getErrorsWhereDocIdDiffersFromFilename(filesToUpload);
-  if (docIdErrors.length > 0) {
-    throw new Error(`upload-docs: ${docIdErrors.join('\n')}`);
-  }
-
-  const totalCount = filesToUpload.length;
+  const filenamesToUpload = fs.recurseFiles(docDir).filter(name => name.endsWith(FILE_EXTENSION));
+  const totalCount = filenamesToUpload.length;
   if (totalCount === 0) {
     return; // nothing to upload
   }
 
-  warn(`This operation will permanently write ${totalCount} docs.  Are you sure you want to continue?`);
-  if (!userPrompt.keyInYN()) {
-    throw new Error('User aborted execution.');
+  const analysis = analyseFiles(filenamesToUpload);
+  const errors = analysis.map(result => result.error).filter(Boolean);
+  if (errors.length > 0) {
+    throw new Error(`upload-docs: ${errors.join('\n')}`);
   }
 
+  userPrompt.warnPromptAbort(`This operation will permanently write ${totalCount} docs.  Are you sure you want to continue?`);
+
+  const deletedDocIds = analysis.map(result => result.delete).filter(Boolean);
+  await handleUsersAtDeletedFacilities(deletedDocIds);
+
   const results = { ok:[], failed:{} };
   const progress = log.level > log.LEVEL_ERROR ? progressBar.init(totalCount, '{{n}}/{{N}} docs ', ' {{%}} {{m}}:{{s}}') : null;
   const processNextBatch = async (docFiles, batchSize) => {
@@ -93,20 +97,102 @@ const execute = async () => {
     }
   };
 
-  return processNextBatch(filesToUpload, INITIAL_BATCH_SIZE);
-};
+  return processNextBatch(filenamesToUpload, INITIAL_BATCH_SIZE);
+}
 
-const getErrorsWhereDocIdDiffersFromFilename = filePaths =>
-  filePaths
+function analyseFiles(filePaths) {
+  return filePaths
     .map(filePath => {
       const json = fs.readJson(filePath);
       const idFromFilename = path.basename(filePath, FILE_EXTENSION);
 
       if (json._id !== idFromFilename) {
-        return `File '${filePath}' sets _id:'${json._id}' but the file's expected _id is '${idFromFilename}'.`;
+        return { error: `File '${filePath}' sets _id:'${json._id}' but the file's expected _id is '${idFromFilename}'.` };
+      }
+
+      if (json._deleted && json.cht_disable_linked_users) {
+        return { delete: json._id };
       }
     })
-    .filter(err => err);
+    .filter(Boolean);
+}
+
+async function handleUsersAtDeletedFacilities(deletedDocIds) {
+  if (!deletedDocIds?.length) {
+    return;
+  }
+
+  await assertCoreVersion();
+  
+  const affectedUsers = await getAffectedUsers(deletedDocIds);
+  const usernames = affectedUsers.map(userDoc => userDoc.username).join(', ');
+  if (affectedUsers.length === 0) {
+    trace('No users found needing an update.');
+    return;
+  }
+
+  userPrompt.warnPromptAbort(`This operation will update ${affectedUsers.length} user accounts: ${usernames} and cannot be undone. Are you sure you want to continue?`);
+  await updateAffectedUsers(affectedUsers);
+}
+
+async function assertCoreVersion() {
+  const actualCoreVersion = await getValidApiVersion();
+  if (semver.lt(actualCoreVersion, '4.7.0-dev')) {
+    throw Error(`CHT Core Version 4.7.0 or newer is required to use --disable-users options. Version is ${actualCoreVersion}.`);
+  }
+
+  trace(`Core version is ${actualCoreVersion}. Proceeding to disable users.`);
+}
+
+async function getAffectedUsers(deletedDocIds) {
+  const toPostApiFormat = (apiResponse) => {
+    const places = Array.isArray(apiResponse.place) ? apiResponse.place.filter(Boolean) : [apiResponse.place];
+    const placeIds = places.map(place => place?._id);
+    return {
+      username: apiResponse.username,
+      place: placeIds,
+    };
+  };
+
+  const knownUserDocs = {};
+  for (const facilityId of deletedDocIds) {
+    const fetchedUserInfos = await api().getUsersAtPlace(facilityId);
+    for (const fetchedUserInfo of fetchedUserInfos) {
+      const userDoc = knownUserDocs[fetchedUserInfo.username] || toPostApiFormat(fetchedUserInfo);
+      removePlace(userDoc, facilityId);
+      knownUserDocs[userDoc.username] = userDoc;
+    }
+  }
+
+  return Object.values(knownUserDocs);
+}
+
+function removePlace(userDoc, placeId) {
+  if (Array.isArray(userDoc.place)) {
+    userDoc.place = userDoc.place
+      .filter(id => id !== placeId);
+  } else {
+    delete userDoc.place;
+  }
+}
+
+async function updateAffectedUsers(affectedUsers) {
+  let disabledUsers = 0, updatedUsers = 0;
+  for (const userDoc of affectedUsers) {
+    const shouldDisable = !userDoc.place || userDoc.place?.length === 0;
+    if (shouldDisable) {
+      trace(`Disabling ${userDoc.username}`);
+      await api().disableUser(userDoc.username);
+      disabledUsers++;
+    } else {
+      trace(`Updating ${userDoc.username}`);
+      await api().updateUser(userDoc);
+      updatedUsers++;
+    }
+  }
+
+  info(`${disabledUsers} users disabled. ${updatedUsers} users updated.`);
+}
 
 module.exports = {
   requiresInstance: true,

package/src/lib/api.js

@@ -39,6 +39,7 @@ const request = {
   get: _request('get'),
   post: _request('post'),
   put: _request('put'),
+  delete: _request('delete'),
 };
 
 const logDeprecatedTransitions = (settings) => {
@@ -98,6 +99,29 @@ const api = {
       .then(() => updateAppSettings(content));
   },
 
+  async getUsersAtPlace(facilityId) {
+    const result = await request.get({
+      uri: `${environment.instanceUrl}/api/v2/users?facility_id=${facilityId}`,
+      json: true,
+    });
+
+    return result || [];
+  },
+
+  disableUser(username) {
+    return request.delete({
+      uri: `${environment.instanceUrl}/api/v1/users/${username}`,
+    });
+  },
+
+  updateUser(userDoc) {
+    return request.post({
+      uri: `${environment.instanceUrl}/api/v1/users/${userDoc.username}`,
+      json: true,
+      body: userDoc,
+    });
+  },
+
   createUser(userData) {
     return request.post({
       uri: `${environment.instanceUrl}/api/v1/users`,

package/src/lib/hierarchy-operations/delete-hierarchy.js

@@ -0,0 +1,46 @@
+const DataSource = require('./hierarchy-data-source');
+const JsDocs = require('./jsdocFolder');
+const lineageConstraints = require('./lineage-constraints');
+const { trace, info } = require('../log');
+
+const prettyPrintDocument = doc => `'${doc.name}' (${doc._id})`;
+async function deleteHierarchy(db, options, sourceIds) {
+  JsDocs.prepareFolder(options);
+  
+  const sourceDocs = await DataSource.getContactsByIds(db, sourceIds);
+  const constraints = await lineageConstraints(db, options);
+  for (const sourceId of sourceIds) {
+    const sourceDoc = sourceDocs[sourceId];
+    trace(`Deleting descendants and reports under: ${prettyPrintDocument(sourceDoc)}`);
+    const descendantsAndSelf = await DataSource.getContactWithDescendants(db, sourceId);
+
+    let affectedReportCount = 0;
+    for (const descendant of descendantsAndSelf) {
+      const toDeleteUsers = options.disableUsers && constraints.isPlace(descendant);
+      JsDocs.deleteDoc(options, descendant, toDeleteUsers);
+      affectedReportCount += await deleteReportsForContact(db, options, descendant);
+    }
+
+    const affectedContactCount = descendantsAndSelf.length;
+    
+    info(`Staged updates to delete ${prettyPrintDocument(sourceDoc)}. ${affectedContactCount.length} contact(s) and ${affectedReportCount} report(s).`);
+  }
+}
+
+async function deleteReportsForContact(db, options, contact) {
+  let skip = 0;
+  let reportBatch;
+  do {
+    reportBatch = await DataSource.getReportsForContacts(db, [], contact._id, skip);
+
+    for (const report of reportBatch) {
+      JsDocs.deleteDoc(options, report);
+    }
+
+    skip += reportBatch.length;
+  } while (reportBatch.length >= DataSource.BATCH_SIZE);
+  
+  return skip;
+}
+
+module.exports = deleteHierarchy;

package/src/lib/hierarchy-operations/index.js

@@ -1,10 +1,10 @@
+const DataSource = require('./hierarchy-data-source');
+const deleteHierarchy = require('./delete-hierarchy');
+const JsDocs = require('./jsdocFolder');
 const lineageManipulation = require('./lineage-manipulation');
 const LineageConstraints = require('./lineage-constraints');
 const { trace, info } = require('../log');
 
-const JsDocs = require('./jsdocFolder');
-const DataSource = require('./hierarchy-data-source');
-
 async function moveHierarchy(db, options, sourceIds, destinationId) {
   JsDocs.prepareFolder(options);
   trace(`Fetching contact details: ${destinationId}`);
@@ -30,11 +30,8 @@ async function moveHierarchy(db, options, sourceIds, destinationId) {
     await constraints.assertNoPrimaryContactViolations(sourceDoc, destinationDoc, descendantsAndSelf);
     
     if (options.merge) {
-      JsDocs.writeDoc(options, {
-        _id: sourceDoc._id,
-        _rev: sourceDoc._rev,
-        _deleted: true,
-      });
+      const toDeleteUsers = options.disableUsers && constraints.isPlace(sourceDoc);
+      JsDocs.deleteDoc(options, sourceDoc, toDeleteUsers);
     }
         
     const prettyPrintDocument = doc => `'${doc.name}' (${doc._id})`;
@@ -176,11 +173,11 @@ function replaceLineageInContacts(moveContext) {
     .filter(Boolean);
 }
 
-module.exports = (db, options) => {
+module.exports = (db, options = {}) => {
   return {
     HIERARCHY_ROOT: DataSource.HIERARCHY_ROOT,
     move: (sourceIds, destinationId) => moveHierarchy(db, { ...options, merge: false }, sourceIds, destinationId),
     merge: (sourceIds, destinationId) => moveHierarchy(db, { ...options, merge: true }, sourceIds, destinationId),
+    delete: async (sourceIds) => deleteHierarchy(db, options, sourceIds),
   };
 };
-

package/src/lib/hierarchy-operations/jsdocFolder.js

@@ -30,7 +30,17 @@ function deleteAfterConfirmation(docDirectoryPath) {
   fs.deleteFilesInFolder(docDirectoryPath);
 }
 
+function deleteDoc(options, doc, disableUsers) {
+  writeDoc(options, {
+    _id: doc._id,
+    _rev: doc._rev,
+    _deleted: true,
+    cht_disable_linked_users: !!disableUsers,
+  });
+}
+
 module.exports = {
+  deleteDoc,
   prepareFolder,
   writeDoc,
 };

package/src/lib/hierarchy-operations/lineage-constraints.js

@@ -5,7 +5,7 @@ const { trace } = log;
 const lineageManipulation = require('./lineage-manipulation');
 
 module.exports = async (db, options) => {
-  const mapTypeToAllowedParents = await fetchAllowedParents(db);
+  const contactTypeInfo = await fetchContactTypeInfo(db);
 
   return {
     assertNoPrimaryContactViolations: async (sourceDoc, destinationDoc, descendantDocs) => {
@@ -20,7 +20,7 @@ module.exports = async (db, options) => {
         const commonViolations = getCommonViolations(sourceDoc, destinationDoc);
         const specificViolation = options.merge ?
           getMergeViolations(sourceDoc, destinationDoc)
-          : getMovingViolations(mapTypeToAllowedParents, sourceDoc, destinationDoc);
+          : getMovingViolations(contactTypeInfo, sourceDoc, destinationDoc);
 
         const hierarchyError = commonViolations || specificViolation;
         if (hierarchyError) {
@@ -41,7 +41,12 @@ module.exports = async (db, options) => {
             throw Error(`Unable to move two documents from the same lineage: '${doc._id}' and '${violatingParentId}'`);
           }
         });
-    }    
+    },
+
+    isPlace: (contact) => {
+      const contactType = getContactType(contact);
+      return !contactTypeInfo[contactType]?.person;
+    },
   };
 };
 
@@ -49,22 +54,22 @@ module.exports = async (db, options) => {
 Enforce the list of allowed parents for each contact type
 Ensure we are not creating a circular hierarchy
 */
-const getMovingViolations = (mapTypeToAllowedParents, sourceDoc, destinationDoc) => {
-  const contactTypeError = getMovingContactTypeError(mapTypeToAllowedParents, sourceDoc, destinationDoc);
+const getMovingViolations = (contactTypeInfo, sourceDoc, destinationDoc) => {
+  const contactTypeError = getMovingContactTypeError(contactTypeInfo, sourceDoc, destinationDoc);
   const circularHierarchyError = findCircularHierarchyErrors(sourceDoc, destinationDoc);
   return contactTypeError || circularHierarchyError;
 };
 
-function getMovingContactTypeError(mapTypeToAllowedParents, sourceDoc, destinationDoc) {
+function getMovingContactTypeError(contactTypeInfo, sourceDoc, destinationDoc) {
   const sourceContactType = getContactType(sourceDoc);
   const destinationType = getContactType(destinationDoc);
-  const rulesForContact = mapTypeToAllowedParents[sourceContactType];
-  if (!rulesForContact) {
+  const parentsForContactType = contactTypeInfo[sourceContactType]?.parents;
+  if (!parentsForContactType) {
     return `cannot move contact with unknown type '${sourceContactType}'`;
   }
 
-  const isPermittedMoveToRoot = !destinationDoc && rulesForContact.length === 0;
-  if (!isPermittedMoveToRoot && !rulesForContact.includes(destinationType)) {
+  const isPermittedMoveToRoot = !destinationDoc && parentsForContactType.length === 0;
+  if (!isPermittedMoveToRoot && !parentsForContactType.includes(destinationType)) {
     return `contacts of type '${sourceContactType}' cannot have parent of type '${destinationType}'`;
   }
 }
@@ -139,9 +144,9 @@ const getPrimaryContactViolations = async (db, contactDoc, destinationDoc, desce
   return descendantDocs.find(descendant => primaryContactIds.some(primaryId => descendant._id === primaryId));
 };
 
-const getContactType = doc => doc && (doc.type === 'contact' ? doc.contact_type : doc.type);
+const getContactType = doc => doc?.type === 'contact' ? doc?.contact_type : doc?.type;
 
-async function fetchAllowedParents(db) {
+async function fetchContactTypeInfo(db) {
   try {
     const { settings: { contact_types } } = await db.get('settings');
 
@@ -150,7 +155,7 @@ async function fetchAllowedParents(db) {
       const parentDict = {};
       contact_types
         .filter(Boolean)
-        .forEach(({ id, parents }) => parentDict[id] = parents);
+        .forEach(({ id, person, parents }) => parentDict[id] = { parents, person: !!person });
       return parentDict;
     }
   } catch (err) {
@@ -161,10 +166,10 @@ async function fetchAllowedParents(db) {
 
   trace('Default hierarchy constraints will be enforced.');
   return {
-    district_hospital: [],
-    health_center: ['district_hospital'],
-    clinic: ['health_center'],
-    person: ['district_hospital', 'health_center', 'clinic'],
+    district_hospital: { parents: [] },
+    health_center: { parents: ['district_hospital'] },
+    clinic: { parents: ['health_center'] },
+    person: { parents: ['district_hospital', 'health_center', 'clinic'], person: true },
   };
 }
 

package/src/lib/user-prompt.js

@@ -1,5 +1,6 @@
 const environment = require('./environment');
 const readline = require('readline-sync');
+const { warn } = require('./log');
 
 
 /**
@@ -33,8 +34,16 @@ function keyInSelect(items, question, options = {}) {
   return readline.keyInSelect(items, question, options);
 }
 
+function warnPromptAbort(warningMessage) {
+  warn(warningMessage);
+  if (!keyInYN()) {
+    throw new Error('User aborted execution.');
+  }
+}
+
 module.exports = {
   keyInYN,
   question,
-  keyInSelect
+  keyInSelect,
+  warnPromptAbort,
 };