# Ephemere

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

## Project Structure

```
.
├── typescript/     # TypeScript project
│   ├── src/       # TypeScript source files
│   ├── package.json
│   ├── tsconfig.json
│   └── eslint.config.js
├── python/        # Python project
│   ├── *.py       # Python scripts
│   ├── pyproject.toml
│   └── requirements.txt
├── Makefile       # Build commands for both projects
└── README.md
```

## Setup

### Prerequisites

- Node.js (v24+) with nvm
- Python 3.10+
- pnpm 10.15.0
- uv (Python package manager)
- 1Password CLI (for secrets management)

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

## Development

### TypeScript Scripts

TypeScript scripts are located in the `typescript/src/` directory. To run a TypeScript script with environment variables:

```bash
# From the root directory
make run-ts src/s3/upload.ts

# Or manually from typescript directory
cd typescript
pnpm start path/to/script.ts
```

### Python Scripts

Python scripts are located in the `python/` directory. To run a Python script with environment variables:

```bash
# From the root directory
make run-py analyse_availability.py

# Or manually from python directory
cd python
uv run python script_name.py
```

## Linting and Formatting

```bash
# Run all linters (TypeScript and Python)
make lint

# Run linters individually
make lint-ts     # TypeScript linter
make lint-py     # Python linter

# Build TypeScript (type check)
make build

# Format Python code
make format

# Check Python formatting without modifying
make format-check

# Run tests
make test

# Clean build artifacts and caches
make clean

# Show all available commands
make help
```

## CI/CD

The GitHub Actions workflow runs the following checks:

1. **Dependency pin check** - Ensures all dependencies are pinned to exact versions
2. **TypeScript checks**:
   - ESLint
   - TypeScript build (type checking)
   - Tests
3. **Python checks**:
   - Ruff linting
   - Ruff format checking

## Secrets Management

This project uses 1Password CLI for secrets management. Environment variables are stored in `prod.env` as 1Password vault references.

The `make run-ts` and `make run-py` commands automatically inject secrets from 1Password:
```bash
# These commands include 1Password integration
make run-ts src/discord/bot.ts
make run-py evaluate_technical_proficiency.py
```

To manually run scripts 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`.