Merge pull request #39 from dyne/account-wizard

feat(account): add interactive account wizard command

Author: jaromil

.github/workflows/pr-tests.yml

@@ -20,12 +20,14 @@ jobs:
           sudo apt-get install --no-install-recommends -y \
             zsh make gcc \
             fetchmail msmtp neomutt notmuch pinentry-curses \
-            abook wipe mblaze gnupg
+            abook wipe mblaze gnupg pandoc
 
       - name: Ensure test scripts are executable
         run: |
           chmod +x extras/test/run-source.sh
           chmod +x extras/test/test-addressbook-parse.sh
+          chmod +x extras/test/test-account-wizard.sh
+          chmod +x extras/test/test-group-modes.sh
           chmod +x extras/test/test-filtering.sh
           chmod +x extras/test/test-sieve-import.sh
           chmod +x extras/test/test-helpers.sh
@@ -39,6 +41,12 @@ jobs:
       - name: Addressbook and parsing tests
         run: extras/test/test-addressbook-parse.sh
 
+      - name: Account wizard tests
+        run: extras/test/test-account-wizard.sh
+
+      - name: Group delivery mode tests
+        run: extras/test/test-group-modes.sh
+
       - name: Filtering tests
         run: extras/test/test-filtering.sh
 

AGENTS.md

@@ -10,6 +10,7 @@ Jaromail is a terminal mail workflow built mostly from Zsh scripts plus small C
 - `make clean`: removes generated helper binaries and object files from `src/`.
 - `sudo make install`: installs Jaromail under `/usr/local/share/jaromail` and creates `/usr/local/bin/jaro`.
 - `extras/test/run-source.sh`: smoke test for the checked-out code; runs `src/jaro` with a local staged install in a temp path.
+- `extras/test/test-account-wizard.sh`: validates the interactive `wizard` account flow using scripted stdin.
 - `./extras/test/inittest.sh`: runs the installed smoke test using `/tmp/jaromail-test`.
 - `PREFIX=/tmp/jaro make install`: checks install layout without touching `/usr/local`; adjust the smoke test paths if using this.
 
@@ -19,7 +20,7 @@ Prefer minimal, readable changes. Keep Zsh functions lowercase, shell modules gr
 
 ## Testing Guidelines
 
-There is no broad unit-test suite. Use `extras/test/run-source.sh` for checkout-level validation and `extras/test/inittest.sh` for installed-path validation. The tests depend on external mail tools (`fetchmail`, `msmtp`, `mutt`/`neomutt`, `notmuch`, `pinentry-curses`, `abook`, `wipe`, `mblaze`/`maddr`) plus build tools from `.travis.yml`. For narrow C helper changes, rebuild with `make` and add a focused command-line check where practical.
+There is no broad unit-test suite. Use `extras/test/run-source.sh` for checkout-level validation, `extras/test/test-account-wizard.sh` for account onboarding behavior, and `extras/test/inittest.sh` for installed-path validation. The tests depend on external mail tools (`fetchmail`, `msmtp`, `mutt`/`neomutt`, `notmuch`, `pinentry-curses`, `abook`, `wipe`, `mblaze`/`maddr`) plus build tools from `.travis.yml`. For narrow C helper changes, rebuild with `make` and add a focused command-line check where practical.
 
 ## Commit & Pull Request Guidelines
 

Makefile

@@ -1,21 +1,35 @@
 PREFIX ?= /usr/local
 JARO_LIBEXEC := ${PREFIX}/share/jaromail
 JARO_SHARE := ${PREFIX}/share/jaromail
+MAN1DIR := ${PREFIX}/share/man/man1
 srcdir := $(shell pwd)
 
 all:
 	./build/auto build
 
+man:
+	@pandoc -s -t man \
+		--metadata title="jaromail" --metadata section="1" \
+		--metadata date="$$(date +%Y-%m-%d)" \
+		${srcdir}/doc/jaromail-manual.md -o ${srcdir}/doc/jaromail.1
+	@pandoc -s -t man \
+		--metadata title="jaro" --metadata section="1" \
+		--metadata date="$$(date +%Y-%m-%d)" \
+		${srcdir}/doc/jaro.1.md -o ${srcdir}/doc/jaro.1
+
 # { test -r $srcdir/src/fetchaddr } || {
 # print "Error: first build, then install."; return 1 }
-install:
+install: man
 	$(info Installing JaroMail in ${JARO_SHARE})
 	@mkdir -p ${JARO_SHARE}/mutt ${JARO_SHARE}/stats
 	@mkdir -p ${JARO_LIBEXEC}/bin ${JARO_LIBEXEC}/zlibs
+	@mkdir -p ${MAN1DIR}
 	@chmod -R a+rX ${JARO_SHARE}
 	@cp -r ${srcdir}/doc/* ${JARO_SHARE}/
 	@cp -r ${srcdir}/src/mutt/* ${JARO_SHARE}/mutt/
 	@cp -r ${srcdir}/src/stats/* ${JARO_SHARE}/stats/
+	@cp ${srcdir}/doc/jaromail.1 ${MAN1DIR}/jaromail.1
+	@cp ${srcdir}/doc/jaro.1 ${MAN1DIR}/jaro.1
 	@cp ${srcdir}/src/jaro ${JARO_LIBEXEC}/bin
 	@cp -r ${srcdir}/build/gnu/* ${JARO_LIBEXEC}/bin
 	@cp -r ${srcdir}/src/zlibs/* ${JARO_LIBEXEC}/zlibs/
@@ -36,5 +50,3 @@ clean:
 	rm -f src/parsedate
 	rm -f src/dotlock
 
-
-

doc/jaro.1

@@ -0,0 +1,131 @@
+.\" Automatically generated by Pandoc 3.1.3
+.\"
+.\" Define V font for inline verbatim, using C font in formats
+.\" that render this, and otherwise B font.
+.ie "\f[CB]x\f[]"x" \{\
+. ftr V B
+. ftr VI BI
+. ftr VB B
+. ftr VBI BI
+.\}
+.el \{\
+. ftr V CR
+. ftr VI CI
+. ftr VB CB
+. ftr VBI CBI
+.\}
+.TH "jaro" "1" "2026-04-30" "" ""
+.hy
+.SH jaro(1)
+.SS Name
+.PP
+jaro - command line interface for Jaromail workflows
+.SS Synopsis
+.PP
+\f[V]jaro [options] [command] [command-options]\f[R]
+.SS Description
+.PP
+\f[V]jaro\f[R] is the operational CLI for Jaromail.
+It orchestrates account configuration, local maildir operations,
+addressbooks, filtering, indexing and SMTP/IMAP actions.
+.SS Options
+.PP
+\f[V]-a ACCOUNT\f[R] use a specific account instead of
+\f[V]default\f[R].
+.PP
+\f[V]-l LIST\f[R] use a specific addressbook/list (default:
+\f[V]whitelist\f[R]).
+.PP
+\f[V]-n\f[R] dry-run mode where supported.
+.PP
+\f[V]-q\f[R] quiet mode.
+.PP
+\f[V]-D\f[R] debug mode.
+.PP
+\f[V]-h\f[R] show help.
+.PP
+\f[V]-v\f[R] show version.
+.PP
+\f[V]-f\f[R] force mode for selected operations.
+.SS Commands
+.SS Core mail flow
+.PP
+\f[V]wizard\f[R] interactive account setup.
+.PP
+\f[V]fetch\f[R] fetch unread messages for an account.
+.PP
+\f[V]send\f[R] send queued messages from \f[V]outbox/\f[R].
+.PP
+\f[V]queue\f[R] read a full message from stdin and queue it.
+.PP
+\f[V]smtp\f[R] read a full message from stdin and send via SMTP.
+.PP
+\f[V]peek\f[R] open remote IMAP mailbox view.
+.PP
+\f[V]open\f[R] open a local maildir folder.
+.SS Account and secrets
+.PP
+\f[V]passwd\f[R] set or update account password in the configured
+keyring.
+.PP
+\f[V]askpass\f[R] print account password resolved from keyring/prompt.
+.PP
+\f[V]isonline\f[R] check network reachability.
+.SS Search and indexing
+.PP
+\f[V]index\f[R] update the search index.
+.PP
+\f[V]search\f[R] run search queries over local mail archives.
+.PP
+\f[V]header\f[R], \f[V]headers\f[R] print mail headers.
+.SS Addressbook and contacts
+.PP
+\f[V]abook\f[R] edit addressbook.
+.PP
+\f[V]addr\f[R], \f[V]list\f[R] list addresses from addressbook.
+.PP
+\f[V]extract\f[R], \f[V]parse\f[R] extract addresses from supported
+inputs.
+.PP
+\f[V]import\f[R] import addresses from stdin.
+.PP
+\f[V]export\f[R] export addresses to another format.
+.PP
+\f[V]learn\f[R], \f[V]isknown\f[R], \f[V]complete\f[R] contact
+learning/query/completion helpers.
+.SS Filtering and Sieve
+.PP
+\f[V]update\f[R] rebuild local filtering cache and regenerate Sieve.
+.PP
+\f[V]filter\f[R] apply filters to a maildir.
+.PP
+\f[V]sieve\f[R] regenerate \f[V]Filters.sieve\f[R] only.
+.PP
+\f[V]sieve-import FILE\f[R] import a Jaromail-generated Sieve file into
+local filter/addressbook files.
+.SS Maildir and utility commands
+.PP
+\f[V]backup\f[R] move search results between maildirs.
+.PP
+\f[V]merge\f[R] merge one maildir into another.
+.PP
+\f[V]deliver\f[R] deliver a message from stdin into a maildir.
+.PP
+\f[V]rmdupes\f[R] remove duplicate messages.
+.PP
+\f[V]remember\f[R], \f[V]replay\f[R], \f[V]preview\f[R], \f[V]edit\f[R],
+\f[V]vim\f[R], \f[V]publish\f[R], \f[V]imap\f[R], \f[V]alot\f[R],
+\f[V]alot-config\f[R], \f[V]notmuch\f[R], \f[V]notmuch-config\f[R],
+\f[V]isml\f[R], \f[V]ismd\f[R].
+.SS Files
+.PP
+\f[V]$JAROMAILDIR\f[R] mail root (default usually \f[V]$HOME/Mail\f[R]).
+.PP
+\f[V]$JAROMAILDIR/Accounts/\f[R] account configuration files.
+.PP
+\f[V]$JAROMAILDIR/Filters.txt\f[R] filtering rules.
+.PP
+\f[V]$JAROMAILDIR/Filters.sieve\f[R] generated Sieve rules.
+.SS See Also
+.PP
+\f[V]jaromail(1)\f[R]

doc/jaro.1.md

@@ -0,0 +1,121 @@
+jaro(1)
+=======
+
+## Name
+
+jaro - command line interface for Jaromail workflows
+
+## Synopsis
+
+`jaro [options] [command] [command-options]`
+
+## Description
+
+`jaro` is the operational CLI for Jaromail. It orchestrates account
+configuration, local maildir operations, addressbooks, filtering,
+indexing and SMTP/IMAP actions.
+
+## Options
+
+`-a ACCOUNT` use a specific account instead of `default`.
+
+`-l LIST` use a specific addressbook/list (default: `whitelist`).
+
+`-n` dry-run mode where supported.
+
+`-q` quiet mode.
+
+`-D` debug mode.
+
+`-h` show help.
+
+`-v` show version.
+
+`-f` force mode for selected operations.
+
+## Commands
+
+### Core mail flow
+
+`wizard` interactive account setup.
+
+`fetch` fetch unread messages for an account.
+
+`send` send queued messages from `outbox/`.
+
+`queue` read a full message from stdin and queue it.
+
+`smtp` read a full message from stdin and send via SMTP.
+
+`peek` open remote IMAP mailbox view.
+
+`open` open a local maildir folder.
+
+### Account and secrets
+
+`passwd` set or update account password in the configured keyring.
+
+`askpass` print account password resolved from keyring/prompt.
+
+`isonline` check network reachability.
+
+### Search and indexing
+
+`index` update the search index.
+
+`search` run search queries over local mail archives.
+
+`header`, `headers` print mail headers.
+
+### Addressbook and contacts
+
+`abook` edit addressbook.
+
+`addr`, `list` list addresses from addressbook.
+
+`extract`, `parse` extract addresses from supported inputs.
+
+`import` import addresses from stdin.
+
+`export` export addresses to another format.
+
+`learn`, `isknown`, `complete` contact learning/query/completion helpers.
+
+### Filtering and Sieve
+
+`update` rebuild local filtering cache and regenerate Sieve.
+
+`filter` apply filters to a maildir.
+
+`sieve` regenerate `Filters.sieve` only.
+
+`sieve-import FILE` import a Jaromail-generated Sieve file into local
+filter/addressbook files.
+
+### Maildir and utility commands
+
+`backup` move search results between maildirs.
+
+`merge` merge one maildir into another.
+
+`deliver` deliver a message from stdin into a maildir.
+
+`rmdupes` remove duplicate messages.
+
+`remember`, `replay`, `preview`, `edit`, `vim`, `publish`, `imap`,
+`alot`, `alot-config`, `notmuch`, `notmuch-config`, `isml`, `ismd`.
+
+## Files
+
+`$JAROMAILDIR` mail root (default usually `$HOME/Mail`).
+
+`$JAROMAILDIR/Accounts/` account configuration files.
+
+`$JAROMAILDIR/Filters.txt` filtering rules.
+
+`$JAROMAILDIR/Filters.sieve` generated Sieve rules.
+
+## See Also
+
+`jaromail(1)`
+

doc/jaromail-manual.md

@@ -970,6 +970,37 @@ Will extract all addresses found in unsorted (the maildir collecting all
 non-mailinglist emails in which we are not an explicit recipient) and
 put them into our blacklist.
 
+### Private recipient groups
+
+You can define reusable recipient groups in `Mail/Groups/` and send to
+them by using the pseudo-address `groupname@jaromail.group`.
+
+Create a group file, for example `Mail/Groups/team`:
+
+``` example
+#mode individual
+Alice <alice@example.org>
+Bob <bob@example.org>
+```
+
+Then compose to the group:
+
+``` example
+jaro compose team@jaromail.group
+```
+
+Group delivery modes are controlled by the first line:
+
+- `#mode individual` (default): one message per recipient, recipients do
+  not see each other.
+- `#mode carboncopy` or `#mode cc`: one message with all recipients in
+  `To:` and `Reply-To:` set to sender address.
+- `#mode bcc`: one message with hidden recipients (`To:
+  undisclosed-recipients:;`) and all recipients in `Bcc:`.
+
+This behavior is implemented in the queueing path, so it also applies
+when messages are piped and queued from stdin.
+
 ### Export to VCard and other formats
 
 VCard is an exchange format useful to interface with other addressbook