# ByteLyst DevOps Tools

Internal repository for GitHub administration scripts, multi-repo safety helpers, and a few adjacent utility projects used by ByteLyst.

This repo is not a single application. It is a workspace of operational tools with three main characteristics:

- The primary surface area is Bash scripts for GitHub and repository operations.
- Some subdirectories are self-contained Python utilities with their own setup and runtime expectations.
- A number of JSON files and outputs are generated artifacts or operational inputs, not source code to edit casually.

## Start Here

If you are new to the repo, read these in order:

1. [docs/getting-started.md](docs/getting-started.md)
2. [docs/repo-map.md](docs/repo-map.md)
3. [docs/tooling-status.md](docs/tooling-status.md)
4. [scripts/README.md](scripts/README.md) for supported standalone operational scripts
5. [AGENTS.md](AGENTS.md) if you are working through an AI coding agent
6. [CLAUDE.md](CLAUDE.md) if you are using Claude Code specifically

## Primary Entry Points

### GitHub Operations

- `./bytelyst-cli.sh`
  - Main unified CLI for common GitHub admin operations.
  - Requires `curl`, `jq`, and `GITHUB_TOKEN`.
- `./remove_user_interactive.sh`
  - Interactive collaborator-removal workflow with repository pattern matching.
- `./remove_user_guided.sh`
  - Guided wrapper around the same removal flow with a more opinionated interactive UX.
- `./remove_user_from_repos.sh`
  - Scripted removal flow suitable for repeatable or semi-automated use.

### Multi-Repo Git Safety

- `git-work-safety-tools/git_repos_status.sh`
- `git-work-safety-tools/git_repos_rebase_commit_push.sh`
- `git-work-safety-tools/multi_repo_safe_push.sh`
- `git-work-safety-tools/multi_repo_status.sh`

These are for scanning many repositories, checking dirty state, and performing safer batch git workflows.

## Repository Layout

### Core Operational Scripts

- Root `*.sh` files
  - Main Bash-based GitHub and maintenance utilities.
- `scripts/`
  - Named operational scripts that are more self-contained than the older root-level helpers.
- `git-work-safety-tools/`
  - Safer multi-repo git helpers.
- `github_access_scripts/`
  - Focused access checks and repo listing utilities.
- `github_repo_scanners/`
  - Scripts plus generated repo/contributor JSON outputs.

### Side Projects

- `Slack Message/`
  - Python CLI for Slack posting and AI-assisted chat.
- `youtube/`
  - YouTube transcript and summarization helpers.
- `supabase monitor/`
  - Separate Python workflow project for YouTube processing despite the directory name.

### Documentation

- `docs/`
  - Canonical onboarding and repo-orientation docs.
- `scripts/README.md`
  - Support and usage conventions for standalone operational scripts.
- Legacy root docs:
  - `README_interactive_script.md`
  - `README_remove_user_script.md`

These older docs are still useful but are no longer the best starting point.

## Setup

### Root Tooling

```bash
./setup.sh
```

This installs the local development hooks and prepares the shell-based workflow.
If `pip3` is unavailable or blocked by an externally managed Python environment, install the distro package first:

```bash
sudo apt-get install -y pre-commit
./setup.sh
```

### Required Dependencies

- `bash`
- `curl`
- `jq`

### Authentication

Most GitHub-facing scripts require:

```bash
export GITHUB_TOKEN=your_token_here
```

Use a token with the minimum permissions required for the task. Many admin flows assume `repo` and `admin:org`.

For scripts that require multi-account scanning, start from:

```bash
cp accounts.example.json accounts.json
```

Then fill in real values locally. `accounts.json` is intentionally ignored from future commits.

## Common Commands

```bash
./bytelyst-cli.sh help
./bytelyst-cli.sh list-public-repos --user <username>
./bytelyst-cli.sh list-private-repos --org <orgname>
./remove_user_interactive.sh
./git-work-safety-tools/git_repos_status.sh
pre-commit run --all-files
```

## Operational Safety

- Treat `accounts.json`, `*.json` account snapshots, `.env` files, and generated collaborator data as potentially sensitive.
- Prefer dry runs or interactive confirmation flows before bulk removal or visibility changes.
- Do not assume every tracked JSON file is a stable source file; many are data snapshots or inputs.
- Review scripts before reuse in automation. Some are one-off operational helpers and may encode assumptions about ByteLyst org structure.

## Notes On Secrets And Outputs

This repo uses example/template files for local credentials and generated outputs should generally stay out of git. If you need local credentials, create untracked local copies such as `accounts.json` or `.env` from the provided examples.

## Contributing

- Keep new docs in `docs/` unless they are tightly scoped to a subproject.
- Prefer adding a short README to a subdirectory instead of expanding the root README with niche workflow details.
- Validate shell scripts with:

```bash
pre-commit run --all-files
```

- When adding new operational scripts, document:
  - required environment variables
  - destructive behavior
  - expected input files
  - example usage