generated from nhcarrigan/template
hikari
ae081cb54c
CI / dependency-pin-check-typescript (pull_request) Successful in 5s
CI / dependency-pin-check-python (pull_request) Successful in 4s
Security Scan and Upload / Security & DefectDojo Upload (pull_request) Successful in 57s
CI / python (pull_request) Successful in 9m33s
CI / typescript (pull_request) Successful in 9m41s
Add Getting Started sections and correct usage commands to all category READMEs (TypeScript, Python, Bash). Update top-level README.md and CLAUDE.md to reflect the Bash language, correct project structure, and accurate make run instructions. Remove completed DOCS_TODO.md.
130 lines
4.1 KiB
Markdown
130 lines
4.1 KiB
Markdown
# 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`.
|