Ephemere

A collection of ephemeral scripts for various tasks, written in TypeScript, Python, and Bash.

Project Structure

.
├── typescript/          # TypeScript scripts
│   └── src/
│       ├── crowdin/    # Crowdin translation management
│       ├── discord/    # Discord bot utilities
│       ├── discourse/  # Discourse forum management
│       ├── gitea/      # Gitea bulk repository operations
│       ├── github/     # GitHub API interactions
│       ├── music/      # Music file metadata tools
│       ├── s3/         # S3-compatible object storage
│       ├── security/   # Security analysis and reporting
│       └── utils/      # Shared utilities
├── python/
│   └── cohort/         # NHCarrigan cohort programme management
├── 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)
├── run.sh              # Interactive script runner
└── Makefile            # Build and utility commands

Setup

Prerequisites

• Node.js (v24+) with nvm
• Python 3.10+
• pnpm 10.15.0+
• uv (Python package manager)
• 1Password CLI (op) — for secret injection into TypeScript and Python scripts
• gh CLI — for Bash scripts that manage GitHub teams
• ykman and yubico-piv-tool — for YubiKey Bash scripts

Installation

Install all dependencies (TypeScript and Python):

make install

Or install individually:

make install-ts  # TypeScript dependencies only
make install-py  # Python dependencies only

Running Scripts

The recommended way to run any script is the interactive runner:

make run

This launches a menu to select a language (TypeScript, Python, or Bash), then a category, then a specific script. TypeScript and Python scripts have secrets injected automatically from prod.env via 1Password CLI. Bash scripts are run directly.

To run a script directly without the interactive runner:

# TypeScript
cd typescript && op run --env-file=../prod.env -- pnpm tsx src/<category>/<script>.ts

# Python
cd python && op run --env-file=../prod.env -- uv run python cohort/<script>.py

# Bash
bash bash/<category>/<script>.sh

Each category has its own README.md with details on every script, its required environment variables, and data file formats.

Development

Linting and Formatting

make lint           # Run all linters (TypeScript and Python)
make lint-ts        # TypeScript linter only
make lint-py        # Python linter only
make build          # TypeScript type check
make format         # Format Python code
make format-check   # Check Python formatting without modifying
make test           # Run tests
make clean          # Clean build artifacts and caches
make help           # Show all available commands

Secrets Management

This project uses 1Password CLI for secrets management. The prod.env file contains 1Password vault references (e.g. op://Private/Discord/token) rather than real values, making it safe to commit.

The interactive runner (make run) handles secret injection automatically. To run a script manually with secrets:

op run --env-file=prod.env -- <command>

Feedback and Bugs

If you have feedback or a bug report, please log a ticket on our forum.

Contributing

If you would like to contribute to the project, you may create a Pull Request containing your proposed changes and we will review it as soon as we are able! Please review our contributing guidelines first.

Code of Conduct

Before interacting with our community, please read our Code of Conduct.

License

This software is licensed under our global software license.

Copyright held by Naomi Carrigan.

Contact

We may be contacted through our Chat Server or via email at contact@nhcarrigan.com.