feat: reorganise bash scripts and add comprehensive documentation (#6)
CI / dependency-pin-check-typescript (push) Successful in 5s
CI / dependency-pin-check-python (push) Successful in 4s
CI / python (push) Successful in 9m28s
CI / typescript (push) Successful in 9m42s
Security Scan and Upload / Security & DefectDojo Upload (push) Successful in 1m39s

## Summary

This PR completes the bash script restructuring and adds comprehensive documentation across all script categories.

### Bash Restructuring

- Moved cohort shell scripts (`remove_github_members.sh`, `update_github_teams.sh`) from `python/cohort/` into a new `bash/cohort/` directory
- Moved existing bash utilities (`add-keys-to-git.sh`, `fix-yubikey-perms.sh`, `list-yubikey-ssh-keys.sh`) into a new `bash/yubikey/` subdirectory
- Updated `run.sh` to support **Bash** as a third language option alongside TypeScript and Python
  - Bash scripts are run directly (no 1Password secret injection needed)
  - Category discovery and script listing works the same as for TS/Python
  - Removed dead "Root Scripts" logic that was no longer needed

### Documentation

Added `README.md` files for all script categories that were missing them:

- `bash/cohort/README.md` — cohort GitHub team management scripts
- `bash/yubikey/README.md` — YubiKey SSH key and permission utilities
- `typescript/src/crowdin/README.md` — Crowdin translation management scripts
- `typescript/src/discord/README.md` — Discord bot utility scripts
- `typescript/src/discourse/README.md` — Discourse forum management scripts
- `typescript/src/gitea/README.md` — Gitea bulk repository operation scripts
- `typescript/src/github/README.md` — GitHub API interaction scripts
- `typescript/src/music/README.md` — Music file metadata tools
- `typescript/src/s3/README.md` — S3-compatible object storage scripts
- `typescript/src/security/README.md` — Security analysis and reporting scripts
- `python/cohort/README.md` — Updated to remove moved shell scripts, fix usage commands

Also updated project-level docs:

- **`README.md`** — Corrected project structure, fixed running instructions (removed references to non-existent `make run-ts`/`make run-py` targets), added Bash prerequisites
- **`CLAUDE.md`** — Updated project overview, structure, development standards, and script-adding guides to reflect the current state of the project

 This PR was created with help from Hikari~ 🌸

Co-authored-by: Naomi Carrigan <commits@nhcarrigan.com>
Reviewed-on: #6
Co-authored-by: Hikari <hikari@nhcarrigan.com>
Co-committed-by: Hikari <hikari@nhcarrigan.com>
This commit was merged in pull request #6.
This commit is contained in:
2026-02-23 20:18:41 -08:00
committed by Naomi Carrigan
parent e481823e06
commit ec58c9c843
65 changed files with 4507 additions and 157 deletions
+46 -31
View File
@@ -4,32 +4,37 @@ This document contains project-specific instructions for working with the Epheme
## Project Overview
Ephemere is a collection of ephemeral scripts for various tasks, written in TypeScript and Python. It contains utilities for:
Ephemere is a collection of ephemeral scripts for various tasks, written in TypeScript, Python, and Bash. It contains utilities for:
- S3 operations (upload, bulk upload, delete, content type correction)
- Discord bot utilities
- Discourse forum management
- Gitea/GitHub operations
- Security analysis tools
- Music-related scripts
- Various utility functions
- Cohort programme management (Python + Bash)
- YubiKey SSH key and permission utilities (Bash)
## Project Structure
```
ephemere/
├── typescript/ # TypeScript scripts
── src/
├── s3/ # S3 operations (upload, delete, bulk operations)
├── discord/ # Discord bot and utilities
├── discourse/ # Discourse forum management
├── gitea/ # Gitea API interactions
├── github/ # GitHub API interactions
├── security/ # Security analysis tools
├── music/ # Music-related utilities
└── utils/ # Shared utilities
│ └── data/ # Data files for S3 uploads
├── python/ # Python scripts
── prod.env # 1Password vault references (safe to commit)
── src/
├── s3/ # S3 operations (upload, delete, bulk operations)
├── discord/ # Discord bot and utilities
├── discourse/ # Discourse forum management
├── gitea/ # Gitea API interactions
├── github/ # GitHub API interactions
├── security/ # Security analysis tools
├── music/ # Music-related utilities
└── utils/ # Shared utilities
├── python/
│ └── cohort/ # Cohort programme management scripts
── bash/
│ ├── cohort/ # GitHub team management for cohorts
│ └── yubikey/ # YubiKey SSH key and permission utilities
├── data/ # Input/output data files (gitignored)
└── prod.env # 1Password vault references (safe to commit)
```
## Development Standards
@@ -37,13 +42,20 @@ ephemere/
### TypeScript Scripts
- All TypeScript scripts must follow Naomi's Node.js project standards
- Use `@nhcarrigan/typescript-config` and `@nhcarrigan/eslint-config`
- Run scripts using the Makefile: `make run-ts src/path/to/script.ts`
- Run scripts using the interactive runner: `make run` (select TypeScript → category → script)
- Interactive scripts should use `@inquirer/prompts` for user input
### Python Scripts
- Use `uv` for package management
- Linting and formatting with `ruff`
- Run scripts using the Makefile: `make run-py script_name.py`
- Scripts live in subdirectories of `python/` (e.g. `python/cohort/`)
- Run scripts using the interactive runner: `make run` (select Python → category → script)
### Bash Scripts
- Scripts live in subdirectories of `bash/` (e.g. `bash/cohort/`, `bash/yubikey/`)
- Run scripts using the interactive runner: `make run` (select Bash → category → script)
- Or run directly: `bash bash/<category>/<script>.sh`
- Bash scripts do not use 1Password injection (they use `gh` CLI auth or system tools)
### S3 Scripts Specifics
All S3 scripts in `typescript/src/s3/` follow these patterns:
@@ -56,22 +68,24 @@ All S3 scripts in `typescript/src/s3/` follow these patterns:
## Running Scripts
Always use the Makefile commands to run scripts (they handle 1Password integration):
Always use the interactive runner to run scripts (it handles 1Password integration for TypeScript and Python):
```bash
# TypeScript scripts
make run-ts src/s3/deleteContents.ts
make run-ts src/discord/bot.ts
# Python scripts
make run-py analyse_availability.py
```
Or use the interactive runner:
```bash
make run # Interactive menu to select language, category, and script
```
Or run directly:
```bash
# TypeScript (from project root)
cd typescript && op run --env-file=../prod.env -- pnpm tsx src/<category>/<script>.ts
# Python (from project root)
cd python && op run --env-file=../prod.env -- uv run python <category>/<script>.py
# Bash (no 1Password needed)
bash bash/<category>/<script>.sh
```
## Script Patterns
### TypeScript Script Template
@@ -232,7 +246,7 @@ The `prod.env` file contains 1Password vault references (like `op://Private/Hetz
5. Consider adding audit logs for security operations
### Adding a new Python script
1. Create the script in `python/`
1. Create the script in the appropriate subdirectory of `python/` (e.g. `python/cohort/`)
2. Use type hints for all functions and variables
3. Follow PEP 8 style guide (enforced by ruff)
4. Add the script to `requirements.txt` if it needs new dependencies
@@ -247,11 +261,12 @@ The `prod.env` file contains 1Password vault references (like `op://Private/Hetz
5. Add unit tests if the utility is complex
### Adding a new script category
1. Create a new directory under `typescript/src/` or in `python/`
1. Create a new directory under `typescript/src/`, `python/`, or `bash/` as appropriate
2. Follow the naming convention (lowercase, descriptive)
3. Create at least one example script showing the pattern
4. Update this CLAUDE.md with specific guidelines for the category
5. Add any new environment variables to prod.env with 1Password references
4. Create a `README.md` in the new directory documenting each script
5. Update this CLAUDE.md with specific guidelines for the category
6. Add any new environment variables to prod.env with 1Password references
## Testing