Merge branch 'main' of https://github.com/CCBR/parkit

Author: kopardev

CHANGELOG.md

@@ -1,36 +1,61 @@
+## v3.0.1
+
+- Added short options for `projark` subcommands (#45, @kopardev):
+  - common: `-f` (`--folder`), `-p` (`--projectnumber`), `-d` (`--datatype`)
+  - deposit: `-t` (`--tarname`), `-s` (`--split-size-gb`), `-k` (`--no-cleanup`)
+  - retrieve: `-n` (`--filenames`), `-u` (`--unsplit`/`--unspilt`)
+- Updated `projectnumber` normalization (#44, @kopardev):
+  - remove repeated leading `ccbr`/`CCBR` prefixes (with optional `_`/`-`)
+  - accept any non-empty remainder (for example `CCBR-abcd` -> `abcd`)
+- Added absolute-path normalization for `--folder` handling in `projark` (#46 @kopardev):
+  - relative paths are resolved to absolute paths before use
+  - trailing slash/non-trailing slash inputs are both supported
+- Hardened tar command construction with shell-safe quoting for paths containing spaces/special characters.
+- Added ISO 8601 timestamps to `projark` log lines. (#47, @kopardev)
+- Added completion/failure email notifications for `projark` (#48, @kopardev):
+  - recipient: `$USER@nih.gov`
+  - sender: `NCICCBR@mail.nih.gov`
+- Added Open OnDemand graphical session detection in runtime checks (future-facing; `projark` still runs only on Helix today).
+- Updated README/MkDocs docs with:
+  - new short-option usage examples
+  - current `projectnumber` behavior
+  - path normalization behavior
+  - timestamped logging and notification behavior
+  - Open OnDemand availability disclaimer (Biowulf-only today; not directly available on Helix)
+
 ## v3.0.0
 
 - Replaced legacy bash `projark` workflow with a Python-native `projark` CLI (`deposit`, `retrieve`) integrated into the `parkit` package.
 - Archived old bash implementation at `legacy/projark_legacy.sh`; `src/parkit/scripts/projark` now points to the Python CLI.
 - Added `projark deposit` end-to-end archival flow with:
-- `checkapisync` preflight gate
-- Helix host enforcement
-- `tmux`/`screen` session enforcement
-- project/datatype normalization
-- scratch staging, tar/filelist generation, md5 generation
-- transfer via `dm_register_directory`
-- cleanup enabled by default (`--no-cleanup` to retain artifacts)
+  - `checkapisync` preflight gate
+  - Helix host enforcement
+  - `tmux`/`screen` session enforcement
+  - project/datatype normalization
+  - scratch staging, tar/filelist generation, md5 generation
+  - transfer via `dm_register_directory`
+  - cleanup enabled by default (`--no-cleanup` to retain artifacts)
 - Added configurable tar split threshold/chunk size for deposit: `--split-size-gb` (default `500` GB).
 - Added human-readable tar size reporting (MB/GB/TB + bytes) in `projark` output.
 - Added `projark retrieve` enhancements:
-- selected-file retrieval with `--filenames`
-- full-collection retrieval when `--filenames` is omitted (`dm_download_collection`)
-- `--unsplit`/`--unspilt` merge support for multiple split tar groups
+  - selected-file retrieval with `--filenames`
+  - full-collection retrieval when `--filenames` is omitted (`dm_download_collection`)
+  - `--unsplit`/`--unspilt` merge support for multiple split tar groups
 - Improved `projark` CLI output with stepwise status messages and consistent step numbering.
 - Added subcommand version support:
-- `projark --version`
-- `projark deposit --version`
-- `projark retrieve --version`
-- all return the same package-aware message
+  - `projark --version`
+  - `projark deposit --version`
+  - `projark retrieve --version`
+  - all return the same package-aware message
 - Suppressed bootstrap Java/environment warnings for version-only invocations.
 - Updated `checkapisync` logic to treat merge-history-only divergence as in-sync when local/upstream trees match.
 - Reworked docs to versioned MkDocs structure with `projark`-first workflows and updated operational guidance.
 - Updated docs/README guidance:
-- use `mamba activate ...` directly
-- initialize mamba only if not already in `PATH`
-- reference HPC_DME setup guide
-- document minimum Java requirement: `HPC_DM_JAVA_VERSION >= 23`
-- standardize guidance to run all operations in `tmux`/`screen`
+  - use `mamba activate ...` directly
+  - initialize mamba only if not already in `PATH`
+  - reference HPC_DME setup guide
+  - document minimum Java requirement: `HPC_DM_JAVA_VERSION >= 23`
+  - standardize guidance to run all operations in `tmux`/`screen`
 - Documentation: Improved code example readability in README. (#34, @kelly-sovacool)
 
 ## v2.2.0

README.md

@@ -40,12 +40,24 @@ Archive (`deposit`) example:
 projark deposit --folder /data/CCBR/projects/CCBR-12345 --projectnumber 12345 --datatype Analysis
 ```
 
+Archive (`deposit`) short-flag example:
+
+```bash
+projark deposit -f /data/CCBR/projects/CCBR-12345 -p CCBR-12345 -d Analysis -s 250 -k
+```
+
 Retrieve selected files example:
 
 ```bash
 projark retrieve --projectnumber 12345 --datatype Analysis --filenames new.tar_0001,new.tar_0002 --unsplit
 ```
 
+Retrieve selected files short-flag example:
+
+```bash
+projark retrieve -p CCBR-12345 -d Analysis -n new.tar_0001,new.tar_0002 -u
+```
+
 Retrieve full collection example (omit `--filenames`):
 
 ```bash
@@ -54,15 +66,41 @@ projark retrieve --projectnumber 12345 --datatype Analysis --unsplit
 
 Useful `deposit` flags:
 
+- `-f, --folder <path>`: input folder to archive.
+- `-p, --projectnumber <value>`: project identifier.
+- `-d, --datatype <Analysis|Rawdata>`: datatype (default `Analysis`).
 - `--tarname <name>.tar`: override default tar name.
-- `--split-size-gb <N>`: split threshold/chunk size (default `500` GB).
-- `--no-cleanup`: keep scratch artifacts after successful transfer.
+- `-t, --tarname <name>.tar`: override default tar name.
+- `-s, --split-size-gb <N>`: split threshold/chunk size (default `500` GB).
+- `-k, --no-cleanup`: keep scratch artifacts after successful transfer.
 
 Useful `retrieve` flags:
 
-- `--filenames a,b,c`: retrieve specific objects.
-- `--unsplit` (alias `--unspilt`): merge downloaded split tar parts.
-- `--folder /path`: override default local base (`/scratch/$USER/CCBR-<projectnumber>`).
+- `-f, --folder /path`: override default local base (`/scratch/$USER/CCBR-<projectnumber>`).
+- `-p, --projectnumber <value>`: project identifier.
+- `-d, --datatype <Analysis|Rawdata>`: datatype (default `Analysis`).
+- `-n, --filenames a,b,c`: retrieve specific objects.
+- `-u, --unsplit` (alias `--unspilt`): merge downloaded split tar parts.
+
+`--projectnumber` normalization:
+
+- Accepts any non-empty value.
+- Repeated leading prefixes `ccbr`, `CCBR`, `Ccbr` are removed (each may be followed by `_`, `-`, or nothing).
+- Examples:
+  - `CCBR-1234` -> `1234`
+  - `CCBR-abcd` -> `abcd`
+  - `ccbr_ccbr-1234abc` -> `1234abc`
+
+Path behavior:
+
+- `--folder FASTQ` and `--folder FASTQ/` are both accepted.
+- Relative `--folder` values are resolved to absolute paths before use.
+
+Runtime logging and notifications:
+
+- Log lines are timestamped in ISO 8601 format (for example `2026-02-19T14:37:52-05:00`).
+- Completion/failure email is sent to `$USER@nih.gov`.
+- Notification sender is `NCICCBR@mail.nih.gov`.
 
 ### Prerequisites:
 
@@ -78,7 +116,8 @@ mamba activate /vf/users/CCBR_Pipeliner/db/PipeDB/miniforge3/envs/parkit
 
 - **HPC_DM_JAVA_VERSION** minimum required value is `23` as of today.
 
-- Run all operations from a `tmux` or `screen` session.
+- Run all operations from `tmux`, `screen`, or an Open OnDemand graphical session.
+- Disclaimer: Open OnDemand is currently available only on Biowulf compute nodes, not directly on Helix. Since `projark` is Helix-only today, use `tmux`/`screen` on Helix; Open OnDemand support is future-facing until Helix access is available.
 
 - If `mamba` is not already in your `PATH`, add the following block to your `~/.bashrc` or `~/.zshrc`, then run `mamba activate /vf/users/CCBR_Pipeliner/db/PipeDB/miniforge3/envs/parkit`:
 

docs/cli/projark-deposit.md

@@ -8,25 +8,34 @@ Archives a local project folder into HPC-DME collection paths under:
 
 ```bash
 projark deposit \
-  --folder /data/CCBR/projects/CCBR-12345 \
-  --projectnumber 12345 \
-  --datatype Analysis
+  -f /data/CCBR/projects/CCBR-12345 \
+  -p CCBR-12345 \
+  -d Analysis
 ```
 
 ## Inputs
 
-- `--folder` (required): local folder to archive.
-- `--projectnumber` (required): accepts `1234`, `ccbr1234`, `CCBR-1234`, `ccbr_1234`.
-- `--datatype` (optional): `Analysis` (default) or `Rawdata` (case-insensitive).
-- `--tarname` (optional): override tar filename (default `ccbr<projectnumber>.tar`).
-- `--split-size-gb` (optional): split threshold/chunk size, default `500`.
-- `--cleanup` / `--no-cleanup`: cleanup is enabled by default.
+- `-f`, `--folder` (required): local folder to archive.
+- `-p`, `--projectnumber`, `--project-number` (required): project identifier.
+- `-d`, `--datatype` (optional): `Analysis` (default) or `Rawdata` (case-insensitive).
+- `-t`, `--tarname` (optional): override tar filename (default `ccbr<projectnumber>.tar`).
+- `-s`, `--split-size-gb` (optional): split threshold/chunk size, default `500`.
+- `--cleanup` / `-k`, `--no-cleanup`: cleanup is enabled by default.
+
+`--projectnumber` normalization:
+
+- Accepts any non-empty value.
+- Repeated leading `ccbr` prefixes are removed (case-insensitive; each may be followed by `_`, `-`, or nothing).
+- Examples:
+  - `CCBR-1234` -> `1234`
+  - `CCBR-abcd` -> `abcd`
+  - `ccbr_ccbr-1234abc` -> `1234abc`
 
 ## Runtime Behavior
 
 1. Sync gate (`checkapisync`)
 2. Helix host check
-3. `tmux`/`screen` session check
+3. `tmux`/`screen`/Open OnDemand graphical session check
 4. Ensure target collections exist (create as needed)
 5. Stage tar + filelist in `/scratch/$USER/CCBR-<projectnumber>/<datatype>/`
 6. Split tar if above split threshold
@@ -36,5 +45,9 @@ projark deposit \
 
 ## Notes
 
-- Run from a `tmux` or `screen` session.
+- Run from `tmux`, `screen`, or an Open OnDemand graphical session.
+- Disclaimer: Open OnDemand is currently available only on Biowulf compute nodes, not directly on Helix. Since `projark` is Helix-only today, use `tmux`/`screen` on Helix; Open OnDemand support is future-facing until Helix access is available.
+- `--folder FASTQ` and `--folder FASTQ/` are both valid for directories.
+- Relative folder paths are converted to absolute paths before use.
 - For raw data, pass `--datatype rawdata`.
+- `projark` sends completion/failure email to `$USER@nih.gov` from `NCICCBR@mail.nih.gov`.

docs/cli/projark-overview.md

@@ -23,4 +23,11 @@ Both subcommands run preflight checks:
 
 - `parkit checkapisync`
 - host must be `helix.nih.gov`
-- session must be inside `tmux` or `screen`
+- session must be inside `tmux`, `screen`, or an Open OnDemand graphical session
+- Disclaimer: Open OnDemand is currently available only on Biowulf compute nodes, not directly on Helix. Since `projark` is Helix-only today, use `tmux`/`screen` on Helix; Open OnDemand support is future-facing until Helix access is available.
+
+## Logging and Notification
+
+- `projark` logs include ISO 8601 timestamps.
+- On completion/failure, `projark` sends an email notification to `$USER@nih.gov`.
+- Notification sender is `NCICCBR@mail.nih.gov`.

docs/cli/projark-retrieve.md

@@ -10,35 +10,45 @@ Selected files:
 
 ```bash
 projark retrieve \
-  --projectnumber 12345 \
-  --datatype Analysis \
-  --filenames new.tar_0001,new.tar_0002 \
-  --unsplit
+  -p CCBR-12345 \
+  -d Analysis \
+  -n new.tar_0001,new.tar_0002 \
+  -u
 ```
 
 Full collection:
 
 ```bash
-projark retrieve --projectnumber 12345 --unsplit
+projark retrieve -p 12345 -u
 ```
 
 ## Inputs
 
-- `--projectnumber` (required)
-- `--datatype` (optional, default `Analysis`)
-- `--folder` (optional): local base folder (default `/scratch/$USER/CCBR-<projectnumber>`)
-- `--filenames` (optional): comma-separated object names; omit for full collection download
-- `--unsplit` / `--unspilt`: merge split tar parts after download
+- `-p`, `--projectnumber`, `--project-number` (required)
+- `-d`, `--datatype` (optional, default `Analysis`)
+- `-f`, `--folder` (optional): local base folder (default `/scratch/$USER/CCBR-<projectnumber>`)
+- `-n`, `--filenames` (optional): comma-separated object names; omit for full collection download
+- `-u`, `--unsplit` / `--unspilt`: merge split tar parts after download
+
+`--projectnumber` normalization:
+
+- Accepts any non-empty value.
+- Repeated leading `ccbr` prefixes are removed (case-insensitive; each may be followed by `_`, `-`, or nothing).
 
 ## Runtime Behavior
 
 1. Sync gate (`checkapisync`)
 2. Helix host check
-3. `tmux`/`screen` session check
+3. `tmux`/`screen`/Open OnDemand graphical session check
 4. Validate source collection exists
 5. Download selected objects (`dm_download_dataobject`) or full collection (`dm_download_collection`)
 6. Optionally merge `*.tar_0001`, `*.tar_0002`, ... into tar files
 
 ## Merge Behavior
 
 `--unsplit` supports multiple split groups in one run.
+Disclaimer: Open OnDemand is currently available only on Biowulf compute nodes, not directly on Helix. Since `projark` is Helix-only today, use `tmux`/`screen` on Helix; Open OnDemand support is future-facing until Helix access is available.
+
+`--folder FASTQ` and `--folder FASTQ/` are both valid for directories.
+Relative folder paths are converted to absolute paths before use.
+`projark` sends completion/failure email to `$USER@nih.gov` from `NCICCBR@mail.nih.gov`.

docs/getting-started.md

@@ -60,7 +60,7 @@ parkit syncapi
 
 ## Session Safety
 
-Run all operations inside `tmux` or `screen`:
+Run all operations inside `tmux`, `screen`, or an Open OnDemand graphical session:
 
 ```bash
 tmux new -s parkit
@@ -69,3 +69,4 @@ screen -S parkit
 ```
 
 `projark deposit` and `projark retrieve` enforce this check.
+Disclaimer: Open OnDemand is currently available only on Biowulf compute nodes, not directly on Helix. Since `projark` is Helix-only today, use `tmux`/`screen` on Helix; Open OnDemand support is future-facing until Helix access is available.

docs/index.md

@@ -4,7 +4,7 @@
 
 For most users, the recommended interface is `projark`, which provides guided `deposit` and `retrieve` workflows for entire CCBR project folder(s).
 
-## In This Version (`v3.0.0`)
+## In This Version (`v3.0.0-dev`)
 
 - New Python-native `projark` command with structured subcommands.
 - `projark deposit` for project archival with sync/host/session preflight checks.
@@ -29,5 +29,8 @@ projark retrieve --help
 ## Notes
 
 - `projark` is intended for Helix (`helix.nih.gov`).
-- All runs should be executed in `tmux` or `screen`.
-- Docs are versioned; this set describes `v3.0.0` behavior.
+- All runs should be executed in `tmux`, `screen`, or an Open OnDemand graphical session.
+- Disclaimer: Open OnDemand is currently available only on Biowulf compute nodes, not directly on Helix. Since `projark` is Helix-only today, use `tmux`/`screen` on Helix; Open OnDemand support is future-facing until Helix access is available.
+- `projark` logs include ISO 8601 timestamps.
+- `projark` sends completion/failure email to `$USER@nih.gov` from `NCICCBR@mail.nih.gov`.
+- Docs are versioned; this set describes `v3.0.0-dev` behavior.

docs/operations.md

@@ -10,7 +10,9 @@ tmux new -s parkit
 screen -S parkit
 ```
 
+Open OnDemand graphical sessions are also accepted.
 `projark` enforces this for both `deposit` and `retrieve`.
+Disclaimer: Open OnDemand is currently available only on Biowulf compute nodes, not directly on Helix. Since `projark` is Helix-only today, use `tmux`/`screen` on Helix; Open OnDemand support is future-facing until Helix access is available.
 
 ## Scratch Paths
 
@@ -34,3 +36,9 @@ Default is `500` GB.
 
 - Default: cleanup enabled after successful deposit.
 - To retain artifacts: `--no-cleanup`.
+
+## Logging and Notifications
+
+- `projark` logs include ISO 8601 timestamps.
+- On completion/failure, `projark` sends email to `$USER@nih.gov`.
+- Notification sender is `NCICCBR@mail.nih.gov`.

docs/release-notes/v3.0.0.md docs/release-notes/v3.0.0-dev.mddocs/release-notes/v3.0.0.md renamed to docs/release-notes/v3.0.0-dev.md

@@ -1,15 +1,21 @@
-# Release Notes: v3.0.0
+# Release Notes: v3.0.0-dev
 
 ## Highlights
 
 - Introduced Python-native `projark` command in package.
 - Added `projark deposit` and `projark retrieve` subcommands.
 - Added sync preflight gate (`parkit checkapisync`) before operations.
-- Added Helix and `tmux`/`screen` preflight checks.
+- Added Helix and session preflight checks (`tmux`, `screen`, or Open OnDemand graphical session).
+- Clarification: Open OnDemand is currently available only on Biowulf compute nodes, not directly on Helix. Since `projark` is Helix-only today, use `tmux`/`screen` on Helix; Open OnDemand support is future-facing until Helix access is available.
 - Added configurable deposit split threshold (`--split-size-gb`, default `500`).
 - Added full-collection retrieval mode when `--filenames` is omitted.
 - Added split-part merge support (`--unsplit`) across multiple tar groups.
 - Archived legacy bash `projark` script.
+- Added short options for `projark` inputs (for example `-f`, `-p`, `-d`, `-n`, `-u`).
+- Added `projectnumber` normalization that strips repeated leading `ccbr` prefixes and accepts any non-empty remainder.
+- Added absolute-path normalization for `--folder` inputs.
+- Added ISO 8601 timestamps in `projark` logs.
+- Added completion/failure email notifications to `$USER@nih.gov` from `NCICCBR@mail.nih.gov`.
 
 ## Behavior Notes
 

docs/troubleshooting.md

@@ -16,7 +16,8 @@ Then rerun your `projark` command.
 
 ## Session Check Failure
 
-If prompted to use `tmux`/`screen`, start one and rerun.
+If prompted to use a session wrapper, start `tmux`/`screen` (or use an Open OnDemand graphical session) and rerun.
+Disclaimer: Open OnDemand is currently available only on Biowulf compute nodes, not directly on Helix. Since `projark` is Helix-only today, use `tmux`/`screen` on Helix; Open OnDemand support is future-facing until Helix access is available.
 
 ## Token/Auth Failures