# 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):

```bash
make install
```

Or install individually:

```bash
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:

```bash
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:

```bash
# 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

```bash
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:

```bash
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](https://support.nhcarrigan.com).

## 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](CONTRIBUTING.md) first.

## Code of Conduct

Before interacting with our community, please read our [Code of Conduct](CODE_OF_CONDUCT.md).

## License

This software is licensed under our [global software license](https://docs.nhcarrigan.com/#/license).

Copyright held by Naomi Carrigan.

## Contact

We may be contacted through our [Chat Server](http://chat.nhcarrigan.com) or via email at `contact@nhcarrigan.com`.