Internals

Project layout

app-secrets.sh        # entry point: sources the libraries, dispatches on $1
sources/
├── __constants.sh        # VERSION, CLI name, config file name
├── __help.sh             # __help
├── __init.sh             # __init   — scaffold .secrets.config.json
├── __read.sh             # __read   — download files
├── __write.sh            # __write  — upload files
├── __doctor.sh           # __doctor — diagnostics
└── helpers/
    ├── __config.sh       # load + parse .secrets.config.json (via jq) into bash vars
    ├── __op_utils.sh     # op/jq checks, sign-in/service-account, vault access,
    │                     # path-field item resolution
    └── __path_utils.sh   # glob/folder pattern translation + path safety gate
tests/                    # bats-core suite
└── helpers/              # stateful fake `op` shim + shared bats setup

The entry point glob-sources sources/helpers/*.sh then sources/*.sh, so every file must be side-effect-free on source (define functions, run nothing). It then dispatches the first argument to the matching __<command> function.

Adding a subcommand

1. Create sources/__foo.sh defining a __foo function (mirror an existing one). Keep sourcing side-effect-free and initialize arrays as local -a x=().
2. Wire foo into the dispatch case in app-secrets.sh, and add a line to __help.
3. Add a bats test under tests/ — use the fake op shim (see tests/op_flow.bats) so nothing touches a real 1Password account.

Conventions

The suite uses bats-core (brew install bats-core) and exercises read/write/doctor end-to-end against a fake op on PATH:

bats tests/
shellcheck app-secrets.sh sources/*.sh sources/helpers/*.sh

bash 3.2. macOS ships bash 3.2, so avoid mapfile/readarray, ${var,,}, and unguarded empty-array expansions. Guard arrays with "${arr[@]+"${arr[@]}"}" and initialize them as local -a x=().

Path handling. Everything is line-based: file names containing newlines, tabs, or backslashes are out of scope. Spaces are fine.