Merge branch 'develop' — v1.0.0 initial release

Includes: dbdump_mongo, dbrestore_mongo, dbutils_mongo

CLAUDE.md

@@ -0,0 +1,64 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Project Overview
+
+A collection of standalone Bash utility scripts for MongoDB operations (backup, restore, local dev environment). No build system, package manager, or test suite — each module is a self-contained shell script.
+
+## Modules
+
+| Module | Script | Purpose |
+|---|---|---|
+| `dbdump_mongo/` | `db-dump.sh` | Dump MongoDB databases across multiple named environments |
+| `dbrestore_mongo/` | `db-restore.sh` | Restore a MongoDB dump to a target instance |
+| `dbutils_mongo/` | `db-start.sh` | Spin up a local MongoDB + Mongo Express via Docker |
+
+## Running the Scripts
+
+```bash
+# Backup — interactive environment picker
+cd dbdump_mongo && bash db-dump.sh
+
+# Restore — interactive backup directory navigator
+cd dbrestore_mongo && bash db-restore.sh
+
+# Local dev database — Docker-based
+cd dbutils_mongo && bash db-start.sh up       # start
+cd dbutils_mongo && bash db-start.sh down      # stop
+cd dbutils_mongo && bash db-start.sh status
+cd dbutils_mongo && bash db-start.sh logs
+cd dbutils_mongo && bash db-start.sh clean     # remove volumes
+cd dbutils_mongo && bash db-start.sh reconfigure
+```
+
+## Environment Setup
+
+Each module requires a `.env` file (copied from the corresponding `.env.example`). The `.env` files are git-ignored. `dbdump_mongo` supports multiple named environments stored as `.env.<name>` files with `chmod 600` permissions.
+
+## Architecture Patterns
+
+All three scripts share the same conventions:
+
+- **Sub-command dispatch**: a `main()` function routes `$1` to `cmd_<action>()` functions.
+- **Colored output**: ANSI escape codes (`\033[...m`) for styled terminal output; consistent separator lines.
+- **Prerequisite checks**: each script validates its required tools (`mongodump`, `mongorestore`, `docker`, `docker compose`) at startup and exits early with a clear message if missing.
+- **Interactive prompts**: `read -p` / `select` menus guide the user through environment selection, directory navigation, and confirmation steps before any destructive action.
+
+### dbdump_mongo — multi-environment credential model
+
+Named environments are stored as `.env.<name>` files alongside the main `.env`. Credentials include `MONGO_USERNAME`, `MONGO_PASSWORD`, `MONGO_HOST`, `MONGO_PORT`, `APP_NAME`. Dumps land in `./dumps/<appName>/<yyyymmdd_hhmm>/`. The script generates MongoDB Atlas-compatible connection strings (ssl, replicaSet flags).
+
+### dbrestore_mongo — backup directory navigation
+
+The script walks through backup directory hierarchies interactively. It detects valid restore targets by checking for `.bson` files (`has_bson_files()`). Before executing `mongorestore`, it shows a summary of connection details and the selected backup path and requires explicit confirmation.
+
+### dbutils_mongo — Docker Compose orchestration
+
+Runs two containers on a `dbutils-network` bridge: MongoDB (configurable port, default `MONGO_PORT`) and Mongo Express (default port `8081`). Data is persisted in named volumes `mongodb-data` and `mongodb-config`. On first run, `setup_credentials()` prompts interactively and writes `.env`. The `mongo-init.js` initializer creates a `dataImportHistory` collection with indexes on `importDate` and `status`.
+
+## External Dependencies
+
+- `mongodump` / `mongorestore` — MongoDB Database Tools (must be installed separately)
+- `docker` + `docker compose` (v2 plugin syntax)
+- `bash` (scripts use `bash`-specific features, not POSIX `sh`)

README.md

@@ -1,3 +1,38 @@
-# adastra_scripts
+# AdAstra Scripts
 
-AdAstra Utility Scripts
+A collection of utility scripts for AdAstra projects. Each script is self-contained and can be used independently.
+
+## Scripts
+
+### MongoDB
+
+| Script | Description |
+|---|---|
+| [`dbdump_mongo/`](dbdump_mongo/) | Backup MongoDB databases with multi-environment support (prod, uat, staging, …) |
+| [`dbrestore_mongo/`](dbrestore_mongo/) | Restore a MongoDB backup with interactive directory navigation |
+| [`dbutils_mongo/`](dbutils_mongo/) | Spin up a local MongoDB + Mongo Express instance via Docker |
+
+#### Typical MongoDB workflow
+
+```bash
+# 1. Backup from a remote MongoDB
+cd dbdump_mongo && ./db-dump.sh dump
+
+# 2. Start a local MongoDB instance
+cd dbutils_mongo && ./db-start.sh up
+
+# 3. Restore the backup locally
+cd dbrestore_mongo && ./db-restore.sh
+```
+
+## Requirements
+
+Each script lists its own requirements in its README. Common dependencies:
+
+- **Bash**
+- **MongoDB Database Tools** (`mongodump` / `mongorestore`) — [download](https://www.mongodb.com/try/download/database-tools)
+- **Docker & Docker Compose** (for `dbutils_mongo` only)
+
+## Author
+
+Julien Gautier — AdAstra