Mass Block [bsky] Reposts [and more]
add CLAUDE.md
i mean this is all obviously vibecoded anyways lolol
+56
+56
CLAUDE.md
+56
CLAUDE.md
···
1
+
# CLAUDE.md
2
+
3
+
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
4
+
5
+
## Project
6
+
7
+
MBR is a single-file interactive CLI tool for batch-blocking engagement on Bluesky (ATProto) posts and profiles. It supports blocking reposts, quotes, replies, likes, and followers/following lists. Uses OAuth for authentication and batched writes with rate-limit handling.
8
+
9
+
Runs on both Bun and Node.js. No build step.
10
+
11
+
## Commands
12
+
13
+
```sh
14
+
bun install # install deps (or npm install)
15
+
bun index.js # run the tool (or node index.js)
16
+
node --test test.js # run tests (node:test built-in)
17
+
```
18
+
19
+
CLI flags: `--delay <ms>`, `--batch <n>`, `--dry-run`, `--no-block-target`, `--output <file>`, `--unblock`, `-h`.
20
+
21
+
## Architecture
22
+
23
+
Everything lives in `index.js` (~1300 lines), organized by section-delimiter comments:
24
+
25
+
- **CLI arg parsing** — runtime detection (Bun vs Node), `node:util.parseArgs`
26
+
- **TID generation** — custom base32 timestamp IDs for ATProto records
27
+
- **CBOR/CAR parsing** — inline minimal decoder (no deps) for fast block extraction from repo dumps
28
+
- **URL/URI resolution** — converts bsky.app URLs to `at://` URIs, resolves handles via Slingshot
29
+
- **External APIs** — Constellation (engagement data), Slingshot (identity), public Bluesky API (counts), PDS (blocks, follows)
30
+
- **OAuth & auth** — `FileStore` class persists sessions to `~/.local/state/mbr/sessions.json`, browser-open flow with SSH/WSL paste fallback
31
+
- **Interactive CLI** — custom multi-select built on `@clack/core`, prompt flow for target + categories + confirmation
32
+
- **Filtering** — deduplicates and excludes self, followers, already-blocked; uses Sets for O(1) lookup
33
+
- **Blocking/unblocking** — batched `applyWrites` with rate-limit backoff, duplicate-error fallback to individual creates
34
+
35
+
Only four functions are exported (for tests): `isProfileUrl`, `resolveMiniDoc`, `filterCandidates`, `writeOutput`.
36
+
37
+
## Key Dependencies
38
+
39
+
- `@atcute/oauth-node-client` — OAuth for ATProto
40
+
- `@clack/core` + `@clack/prompts` — interactive CLI primitives
41
+
- `picocolors` — terminal colors
42
+
43
+
## Environment Variables
44
+
45
+
| var | default |
46
+
|-----|---------|
47
+
| `CONSTELLATION_BASE` | `https://constellation.microcosm.blue` |
48
+
| `SLINGSHOT_BASE` | `https://slingshot.microcosm.blue` |
49
+
| `XDG_STATE_HOME` | `~/.local/state` (for session storage) |
50
+
51
+
## Patterns to Know
52
+
53
+
- Fast-path block fetching downloads the full repo CAR file and parses dag-cbor inline rather than using API pagination
54
+
- Rate limit handling reads `ratelimit-*` headers and does adaptive backoff; 429s trigger full wait
55
+
- Batch write failures from duplicates fall back to individual creates
56
+
- OAuth sessions are cached per-DID with scope validation on restore