cht-conf 5.4.0 → 5.6.0

package/AGENTS.md

@@ -0,0 +1,187 @@
+# AGENTS.md
+
+## Setup
+
+### Requirements
+
+- Node.js >=20.0.0
+- Python 3
+- Git (for development)
+
+### Environment
+
+- Docker (required for E2E tests via CHT Docker Helper)
+- Internet connection (for downloading dependencies)
+
+### Installation
+
+```bash
+# Install cht-conf globally
+npm install -g cht-conf
+
+# Install required Python dependency
+pip install git+https://github.com/medic/pyxform.git@medic-conf-1.17#egg=pyxform-medic
+
+# For local development
+git clone https://github.com/medic/cht-conf.git
+cd cht-conf
+npm ci
+```
+
+
+## Build & Test
+
+```bash
+# Code Quality
+npm run eslint                # Run linting checks
+
+# Testing
+npm test                      # Run unit tests with Mocha and NYC coverage
+npm run test-e2e              # Run end-to-end tests (requires Docker)
+
+# Build and Maintenance
+npm run clean                 # Clean build directory
+
+# Development
+node src/bin/index.js <actions>  # Run locally for development
+```
+
+## Project Structure
+
+```
+cht-conf/
+├── bin/                  # Binary executables used by the application
+├── src/                  # Source code
+│   ├── bin/              # Entry point scripts and shell integrations
+│   ├── cli/              # Command-line interface code
+│   ├── contact-summary/  # Contact summary utilities
+│   ├── fn/               # Core functionality implementations (actions)
+│   ├── lib/              # Shared libraries and utilities
+│   │   └── validation/   # Form validation modules
+│   └── nools/            # Rule engine related code
+└── test/                 # Test code
+    ├── contact-summary/  # Tests for contact summary features
+    ├── e2e/              # End-to-end tests
+    ├── fn/               # Tests for core functionality
+    ├── lib/              # Tests for shared libraries
+    └── nools/            # Tests for nools rules
+```
+
+## Code Conventions
+
+### Action Module Pattern
+
+Files in `src/fn/` use this pattern:
+
+```javascript
+module.exports = {
+  requiresInstance: true, // Whether connection to CHT is needed
+  execute: async () => {
+    // Implementation
+  },
+};
+```
+
+### Form Validation Pattern
+
+Files in `src/lib/validation/form/` use this pattern:
+
+```javascript
+module.exports = {
+  requiresInstance: false,
+  skipFurtherValidation: true,
+  execute: async ({ xformPath, xmlStr, xmlDoc, apiVersion }) => {
+    // Implementation
+  },
+};
+```
+
+### Code Style
+
+- ESLint enforces:
+  - ES2022 syntax
+  - Single quotes (template literals allowed)
+  - Semicolons required
+  - No console logging
+  - Strict equality (===)
+  - Extends @medic ESLint config
+- EditorConfig settings:
+  - 2-space indentation
+  - LF line endings
+  - UTF-8 encoding
+  - Final newline in files
+
+### Testing Framework
+
+- Mocha for test runner
+- Chai for assertions (with chai-as-promised and other plugins)
+- NYC for code coverage
+- Sinon for mocks and stubs
+- Tests mirror the src directory structure
+- E2E tests use CHT Docker Helper
+
+## PR & CI Guidelines
+
+### Commit Format
+
+The project uses [Conventional Commits](https://www.conventionalcommits.org/) enforced by commitlint:
+
+```
+feat(scope): add new feature
+fix(scope): fix bug
+docs(scope): update documentation
+chore(scope): update tooling
+```
+
+### Branches
+
+- Main branch: `main`
+- PRs should be created against the `main` branch
+
+### CI Process
+
+GitHub Actions workflow runs:
+
+- Lint checks (`npm run eslint`)
+- Unit tests (`npm test`)
+- E2E tests (`npm run test-e2e`)
+- Tests across multiple Node.js versions (20.x, 22.x, 24.x)
+
+### Semantic Versioning
+
+The project uses semantic-release for automated versioning based on commit messages.
+
+## Notes for AI Agents
+
+- Use `npm test` for unit tests and `npm run test-e2e` for integration tests.
+- All new code should include corresponding tests in the mirrored `test/` directory.
+- Follow the Action Module Pattern for new functionality in `src/fn/`.
+- Form validation modules should follow the Form Validation Pattern in `src/lib/validation/form/`.
+- PRs must pass CI (lint + tests) before merging.
+- All commits should follow the Conventional Commits format.
+
+## Security Considerations
+
+- Do not commit secrets or environment variables.
+- Use the provided API abstractions in `src/lib/` rather than direct connections.
+- Follow project ESLint rules to avoid unsafe code patterns.
+- Authentication credentials should be handled securely through the CLI parameters.
+
+## CLI Usage
+
+```bash
+# Default workflow with local CHT instance
+cht --local
+
+# Specific action
+cht --local upload-app-forms
+
+# Filter forms
+cht --local upload-app-forms -- form1 form2
+
+# Archive mode
+cht --archive --destination=<path>
+
+# Run locally for development
+node src/bin/index.js <action>
+```

package/CHANGELOG.md

@@ -1,3 +1,17 @@
+# [5.6.0](https://github.com/medic/cht-conf/compare/v5.5.0...v5.6.0) (2025-12-15)
+
+
+### Features
+
+* **#772:** allow multiple sms recipients ([3647c7c](https://github.com/medic/cht-conf/commit/3647c7c18003280e7c461b63eac6466221e2474e)), closes [#772](https://github.com/medic/cht-conf/issues/772)
+
+# [5.5.0](https://github.com/medic/cht-conf/compare/v5.4.0...v5.5.0) (2025-10-08)
+
+
+### Features
+
+* **#753:** add deprecated `tel` type form validation ([#754](https://github.com/medic/cht-conf/issues/754)) ([e701b69](https://github.com/medic/cht-conf/commit/e701b691823e535d71e460f0300624642dafe270)), closes [#753](https://github.com/medic/cht-conf/issues/753)
+
 # [5.4.0](https://github.com/medic/cht-conf/compare/v5.3.0...v5.4.0) (2025-09-11)
 
 

package/README.md

@@ -1,360 +1,16 @@
-CHT App Configurer
-========================
+# CHT Conf
+![GitHub license](https://img.shields.io/github/license/medic/cht-conf)
+![GitHub release](https://img.shields.io/github/v/release/medic/cht-conf)
+[![Discourse](https://img.shields.io/badge/discourse-join-blue)](https://forum.communityhealthtoolkit.org/)
 
-CHT Conf is a command-line interface tool to manage and configure your apps built using the [Core Framework](https://github.com/medic/cht-core) of the [Community Health Toolkit](https://communityhealthtoolkit.org).
+CHT Conf is a command-line interface tool to manage and configure apps built using the [CHT Core Framework](https://github.com/medic/cht-core).
 
-# Requirements
+Instructions on how to use this tool can be found on [the CHT documentation site](https://docs.communityhealthtoolkit.org/community/contributing/code/cht-conf/).
 
-* nodejs 18 or later
-* python 3
-* or Docker
-
-# Installation
-
-## Operating System Specific
-
-### Ubuntu
-
-	npm install -g cht-conf
-	sudo python -m pip install git+https://github.com/medic/pyxform.git@medic-conf-1.17#egg=pyxform-medic
-
-### OSX
-
-	npm install -g cht-conf
-	pip install git+https://github.com/medic/pyxform.git@medic-conf-1.17#egg=pyxform-medic
-
-### Windows
-
-As Administrator:
-
-	npm install -g cht-conf
-	python -m pip install git+https://github.com/medic/pyxform.git@medic-conf-1.17#egg=pyxform-medic --upgrade
-
-### Docker
-
-CHT Conf can also be run from within a Docker container. This is useful if you are already familiar with Docker and do not wish to configure the various dependencies required for developing CHT apps on your local machine. The necessary dependencies are pre-packaged in the Docker image.
-
-#### Using the image
-
-The Docker image can be used as a [VS Code Development Container](https://code.visualstudio.com/docs/devcontainers/containers) (easiest) or as a standalone Docker utility.
-
-Install [Docker](https://www.docker.com/). If you are using Windows, you also need to enable the [Windows Subsystem for Linux (WSL2)](https://learn.microsoft.com/en-us/windows/wsl/install) to perform the following steps.
-
-##### VS Code Development Container
-
-If you want to develop CHT apps with VS Code, you can use the Docker image as a Development Container. This will allow you to use the `cht` utility and its associated tech stack from within VS Code (without needing to install dependencies like NodeJS on your host system).
-
-See the [CHT Documentation](https://docs.communityhealthtoolkit.org/apps/tutorials/local-setup/#developing-with-vs-code-dev-container) for more information on building CHT apps with VS Code Development Containers.
-
-##### Standalone Docker utility
-
-If you are not using VS Code, you can use the Docker image as a standalone utility from the command line.  Instead of using the `cht ...` command, you can run `docker run -it --rm -v "$PWD":/workdir medicmobile/cht-app-ide ...`. This will create an ephemeral container with access to your current directory that will run the given cht command. (Do not include the `cht` part of the command, just your desired actions/parameters.)
-
-Run the following command inside the project directory to bootstrap your new CHT project:
-
-```shell
-docker run -it --rm -v "$PWD":/workdir medicmobile/cht-app-ide initialise-project-layout
-```
-
-#### Note on connecting to a local CHT instance
-
-When using `cht` within a Docker container to connect to a CHT instance that is running on your local machine (e.g. a development instance), you cannot use the `--local` flag or `localhost` in your `--url` parameter (since these will be interpreted as "local to the container"). 
-
-It is recommended to run a local CHT instance using the [CHT Docker Helper script](https://docs.communityhealthtoolkit.org/apps/guides/hosting/4.x/app-developer/). You can connect to the resulting `...my.local-ip.co` URL from the Docker container (or the VS Code terminal). (Just make sure the port your CHT instance is hosted on is not blocked by your firewall). 
-
-## Bash completion
-
-To enable tab completion in bash, add the following to your `.bashrc`/`.bash_profile`:
-
-	eval "$(cht --shell-completion=bash)"
-
-## Zsh completion
-To enable tab completion in zsh, add the following to your `~/.zshrc` file:
-   
-    eval "$(cht --shell-completion=zsh)"
-	
-## Upgrading
-
-To upgrade to the latest version
-
-	npm install -g cht-conf
-
-## Usage
-
-`cht` will upload the configuration **from your current directory**.
-
-## Specifying the server to configure
-
-If you are using the default actionset, or performing any actions that require a CHT instance to function (e.g. `upload-xyz` or `backup-xyz` actions) you must specify the server you'd like to function against.
-
-### localhost
-
-For developers, this is the instance defined in your `COUCH_URL` environment variable.
-
-	cht --local
-
-### A specific Medic-hosted instance
-
-For configuring Medic-hosted instances.
-
-	cht --instance=instance-name.dev
-
-Username `admin` is used. A prompt is shown for entering password.
-
-If a different username is required, add the `--user` switch:
-
-	--user user-name --instance=instance-name.dev
-
-### An arbitrary URL
-
-	cht --url=https://username:password@example.com:12345
-
-**NB** - When specifying the URL with `--url`, be sure not to specify the CouchDB database name in the URL. The CHT API will find the correct database.
-
-### Using a session token for authentication
-
-CHT Conf supports authentication using a session token by adding `--session-token` parameter:
-
-	cht --url=https://example.com:12345 --session-token=*my_token* 
-
-The `my_token` can be obtained by doing a POST request to `/_session` [endpoint](https://docs.couchdb.org/en/stable/api/server/authn.html#cookie-authentication) with `name` and `password` as form parameters.  
-
-For example, if your CHT instance is `my.cht.com`, you could use this `curl` call to specify your user `medic` and your password `secret123` to retrieve the header with the `AuthSession` value which is the token:
-
-```
-curl -v  -H 'Content-Type: application/json' -d '{"name":"medic","password":"secret123"}'  https://my.cht.com/_session 2>&1 | grep AuthSession 
-< set-cookie: AuthSession=bWVkaWM6NjdBRTM4MkE6EguRnzpSiK0t8wFaOQ_jgkZE8UWcgNWgpyStzbbHreI; Version=1; Expires=Fri, 13-Feb-2026 18:21:30 GMT; Max-Age=31536000; Path=/; HttpOnly
-```
-### Into an archive to be uploaded later
-
-    cht --archive
-
-The resulting archive is consumable by CHT API >v3.7 to create default configurations.
-
-## Perform specific action(s)
-
-	cht <--archive|--local|--instance=instance-name|--url=url> <...action>
-
-The list of available actions can be seen via `cht --help`.
-
-## Perform actions for specific forms
-
-	cht <--local|--instance=instance-name|--url=url> <...action> -- <...form>
-
-## Protecting against configuration overwriting
-
-_Added in v3.2.0_
-
-In order to avoid overwriting someone else's configuration cht-conf records the last uploaded configuration snapshot in the `.snapshots` directory. The `remote.json` file should be committed to your repository along with the associated configuration change. When uploading future configuration if cht-conf detects the snapshot doesn't match the configuration on the server you will be prompted to overwrite or cancel.
-
-# Currently supported
-
-## Settings
-
-* compile app settings from:
-  - tasks
-  - rules
-  - schedules
-  - contact-summary
-  - purge
-* app settings can also be defined in a more modular way by having the following files in app_settings folder:
-	- base_settings.json
-	- forms.json
-	- schedules.json
-* backup app settings from server
-* upload app settings to server
-* upload resources to server
-* upload custom translations to the server
-* upload privacy policies to server
-* upload branding to server
-* upload partners to server
-* upload database indexes to server
-
-## Forms
-
-* fetch from Google Drive and save locally as `.xlsx`
-* backup from server
-* delete all forms from server
-* delete specific form from server
-* upload all app or contact forms to server
-* upload specified app or contact forms to server
-
-## Managing data and images
-
-* convert CSV files with contacts and reports to JSON docs
-* move contacts by downloading and making the changes locally first
-* upload JSON files as docs on instance
-* compress PNGs and SVGs in the current directory and its subdirectories
-
-## Editing contacts across the hierarchy.
-To edit existing couchdb documents, create a CSV file that contains the id's of the document you wish to update, and the columns of the document attribute(s) you wish to add/edit. By default, values are parsed as strings. To parse a CSV column as a JSON type, refer to the [Property Types](#property-types) section to see how you can parse the values to different types. Also refer to the [Excluded Columns](#excluded-columns) section to see how to exclude column(s) from being added to the docs.
-
-Parameter | Description | Required
--- | -- | --
-column(s) | Comma delimited list of columns you wish to add/edit. If this is not specified all columns will be added. | No
-docDirectoryPath | This action outputs files to local disk at this destination | No. Default `json-docs`
-file(s) | Comma delimited list of files you wish to process using edit-contacts. By default, contact.csv is searched for in the current directory and processed. | No.
-updateOfflineDocs | If passed, this updates the docs already in the docDirectoryPath instead of downloading from the server. | No.
-
-
-### Example
-1. Create a contact.csv file with your columns in the csv folder in your current path. The documentID column is a requirement. (The documentID column contains the document IDs to be fetched from couchdb.)
-
-	| documentID | is_in_emnch:bool |
-	| ----------------- | ---------------- |
-	| documentID1            | false            |
-	| documentID2            | false            |
-	| documentID3            | true             |
-
-1. Use the following command to download and edit the documents:
-
-	```
-	cht --instance=*instance* edit-contacts -- --column=*is_in_emnch* --docDirectoryPath=*my_folder*
-	```
-	or this one to update already downloaded docs
-	```
-	cht --instance=*instance* edit-contacts -- --column=*is_in_emnch* --docDirectoryPath=*my_folder* --updateOfflineDocs
-	```
-1. Then upload the edited documents using the [upload-docs ](#examples) command.
-
-
-# Project layout
-
-This tool expects a project to be structured as follows:
-
-	example-project/
-		.eslintrc
-		app_settings.json
-		contact-summary.js
-		privacy-policies.json
-		privacy-policies/
-		    language1.html
-		    …
-		purge.js
-		resources.json
-		resources/
-			icon-one.png
-			…
-		targets.js
-		tasks.js
-		task-schedules.json
-		forms/
-			app/
-				my_project_form.xlsx
-				my_project_form.xml
-				my_project_form.properties.json
-				my_project_form-media/
-					[extra files]
-					…
-			contact/
-				person-create.xlsx
-				person-create.xml
-				person-create-media/
-					[extra files]
-					…
-			…
-			…
-		translations/
-			messages-xx.properties
-			…
-
-If you are starting from scratch you can initialise the file layout using the `initialise-project-layout` action:
-
-    cht initialise-project-layout
-
-## Derived configs
-
-Configuration can be inherited from another project, and then modified.  This allows the `app_settings.json` and contained files (`task-schedules.json`, `targets.json` etc.) to be imported, and then modified.
-
-To achieve this, create a file called `settings.inherit.json` in your project's root directory with the following format:
-
-	{
-		"inherit": "../path/to/other/project",
-		"replace": {
-			"keys.to.replace": "value-to-replace-it-with"
-		},
-		"merge": {
-			"complex.objects": {
-				"will_be_merged": true
-			}
-		},
-		"delete": [
-			"all.keys.listed.here",
-			"will.be.deleted"
-		],
-		"filter": {
-			"object.at.this.key": [
-				"will",
-				"keep",
-				"only",
-				"these",
-				"properties"
-			]
-		}
-	}
-
-# Development
-
-To develop a new action or improve an existing one, check the ["Actions" doc](src/fn/README.md).
-
-## Testing
-
-### Unit tests
-
-Execute `npm test` to run static analysis checks and the test suite. Requires Docker to run integration tests against a CouchDB instance. 
-
-### End-to-end tests
-
-Run `npm run test-e2e` to run the end-to-end test suite against an actual CHT instance locally. These tests rely on [CHT Docker Helper](https://docs.communityhealthtoolkit.org/hosting/4.x/app-developer/#cht-docker-helper-for-4x) to spin up and tear down an instance locally.
-
-The code interfacing with CHT Docker Helper lives in [`test/e2e/cht-docker-utils.js`](./test/e2e/cht-docker-utils.js). You should rely on the API exposed by this file to orchestrate CHT instances for testing purposes. It is preferable to keep the number of CHT instances orchestrated in E2E tests low as it takes a non-negligible amount of time to spin up an instance and can quickly lead to timeouts.
-
-## Executing your local branch
-
-1. Clone the project locally
-1. Make changes to cht-conf or checkout a branch for testing
-1. Test changes
-	1. To test CLI changes locally you can run `node <project_dir>/src/bin/index.js`. This will run as if you installed via npm.
-	1. To test changes that are imported in code run `npm install <project_dir>` to use the local version of cht-conf.
-
-## Releasing
-
-1. Create a pull request with prep for the new release. 
-1. Get the pull request reviewed and approved.
-1. When doing the squash and merge, make sure that your commit message is clear and readable and follows the strict format described in the commit format section below. If the commit message does not comply, automatic release will fail.
-1. In case you are planning to merge the pull request with a merge commit, make sure that every commit in your branch respects the format. 
-
-### Commit format
-The commit format should follow this [conventional-changelog angular preset](https://github.com/conventional-changelog/conventional-changelog/tree/master/packages/conventional-changelog-angular). Examples are provided below.
-
-Type | Example commit message | Release type
--- | -- | --
-Bug fixes | fix(#123): infinite spinner when clicking contacts tab twice | patch
-Performance | perf(#789): lazily loaded angular modules | patch
-Features | feat(#456): add home tab | minor
-Non-code | chore(#123): update README | none
-Breaking| perf(#2): remove reporting rates feature <br/> BREAKING CHANGE: reporting rates no longer supported | major
-
-
-
-### Releasing betas
-
-1. Checkout the default branch, for example `main`
-1. Run `npm version --no-git-tag-version <major>.<minor>.<patch>-beta.1`. This will only update the versions in `package.json` and `package-lock.json`. It will not create a git tag and not create an associated commit.
-1. Run `npm publish --tag beta`. This will publish your beta tag to npm's beta channel.
-
-To install from the beta channel, run `npm install cht-conf@beta`.
-
-## Build status
-
-Builds brought to you courtesy of GitHub actions. 
-
-<img src="https://github.com/medic/cht-conf/actions/workflows/build.yml/badge.svg">
-
-# Copyright
+## Copyright
 
 Copyright 2013-2025 Medic Mobile, Inc. <hello@medic.org>
 
-# License
+## License
 
 The software is provided under AGPL-3.0. Contributions to this project are accepted under the same license.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cht-conf",
-  "version": "5.4.0",
+  "version": "5.6.0",
   "description": "Configure CHT deployments",
   "main": "./src/lib/main.js",
   "engines": {
@@ -37,13 +37,13 @@
     "@xmldom/xmldom": "^0.8.10",
     "async-retry": "^1.3.3",
     "canonical-json": "0.0.4",
-    "csv-parse": "^5.6.0",
+    "csv-parse": "^6.1.0",
     "dom-compare": "^0.6.0",
     "eslint": "^8.57.1",
     "eslint-webpack-plugin": "^4.2.0",
     "googleapis": "^144.0.0",
     "iso-639-1": "^3.1.5",
-    "joi": "^17.13.3",
+    "joi": "^18.0.1",
     "json-diff": "^1.0.6",
     "json-stringify-safe": "^5.0.1",
     "json2csv": "^5.0.7",
@@ -63,16 +63,16 @@
     "redact-basic-auth": "^1.0.1",
     "request": "^2.88.2",
     "request-promise-native": "^1.0.9",
-    "semver": "^7.7.1",
-    "svgo": "^3.3.2",
+    "semver": "^7.7.3",
+    "svgo": "^4.0.0",
     "terser-webpack-plugin": "^5.3.11",
     "uuid": "^11.1.0",
-    "webpack": "^5.98.0",
+    "webpack": "^5.102.1",
     "xpath": "0.0.34"
   },
   "devDependencies": {
-    "@commitlint/cli": "^19.7.1",
-    "@commitlint/config-conventional": "^19.7.1",
+    "@commitlint/cli": "^20.1.0",
+    "@commitlint/config-conventional": "^20.0.0",
     "@medic/eslint-config": "^1.1.0",
     "@semantic-release/changelog": "^6.0.3",
     "@semantic-release/git": "^10.0.1",
@@ -82,16 +82,16 @@
     "chai-exclude": "^2.1.1",
     "chai-shallow-deep-equal": "^1.4.6",
     "chai-xml": "^0.4.1",
-    "eslint-plugin-n": "^17.15.1",
+    "eslint-plugin-n": "^17.23.1",
     "express": "^4.21.2",
     "express-pouchdb": "^4.2.0",
-    "fs-extra": "11.3.0",
+    "fs-extra": "11.3.2",
     "husky": "^9.1.7",
-    "mocha": "^11.1.0",
+    "mocha": "^11.7.5",
     "nyc": "^17.1.0",
     "pouchdb-adapter-memory": "^9.0.0",
-    "rewire": "^8.0.0",
-    "semantic-release": "^24.2.4",
+    "rewire": "^9.0.1",
+    "semantic-release": "^25.0.2",
     "sinon": "^21.0.0"
   }
 }

package/src/lib/validate-app-settings.js

@@ -58,7 +58,7 @@ const ScheduleSchema = joi.array().items(
         offset: joi.string().required(),
         send_day: joi.string().allow(''),
         send_time: joi.string().allow(''),
-        recipient: joi.string()
+        recipient: joi.alternatives().try(joi.string(), joi.array())
       })
     ).required()
   })

package/src/lib/validation/form/deprecated-tel-type.js

@@ -0,0 +1,36 @@
+const semver = require('semver');
+const { getBindNodes } = require('../../forms-utils');
+
+const validateDeprecatedTelType = async({xformPath, xmlDoc, apiVersion}) => {
+  if(!apiVersion)
+  {
+    return {errors:[], warnings:[]};
+  }
+
+  if(semver.lt(apiVersion, '4.11.0'))
+  {
+    return {errors:[], warnings:[]};
+  }
+
+  const warnings = [];
+
+  const telNodesets = getBindNodes(xmlDoc)
+    .filter(bind => bind.getAttribute('type') === 'tel')
+    .map(bind => bind.getAttribute('nodeset'))
+    .filter(Boolean);
+    
+  if(telNodesets.length)
+  {
+    warnings.push(
+      `Form at ${xformPath} contains the following phone number fields with the deprecated 'tel' type [${telNodesets.join(', ')}]. Follow the documentation to update these fields to the supported type:\nhttps://docs.communityhealthtoolkit.org/building/forms/app/#phone-number-input`
+    );
+  }
+
+  return {errors:[], warnings};
+};
+
+module.exports = {
+  requiresInstance: true,
+  skipFurtherValidation: false,
+  execute: validateDeprecatedTelType
+};