76 lines
3.2 KiB
Markdown
76 lines
3.2 KiB
Markdown
# AI Agent Guidelines
|
|
|
|
## Project Overview
|
|
|
|
Reads Slack messages from the local Chromium IndexedDB cache on disk. Slack's
|
|
desktop app (Mac App Store) persists its entire Redux state as a single
|
|
Blink-serialized blob. We decode it with `dfindexeddb` and extract messages,
|
|
channels, members, etc.
|
|
|
|
## Project Structure
|
|
|
|
```
|
|
.
|
|
├── slack_cli/ # Python package (canonical source)
|
|
│ ├── __init__.py
|
|
│ └── __main__.py # CLI entry point
|
|
├── pyproject.toml # Python packaging metadata
|
|
├── flake.nix # Nix dev shell + package build
|
|
├── docs/
|
|
│ └── indexeddb-format.md # Full IndexedDB data format documentation
|
|
└── scripts/
|
|
└── analyze_structure.py # Generates schema data for docs
|
|
```
|
|
|
|
## Key Files
|
|
|
|
- **`slack_cli/__main__.py`** — Canonical CLI source. Entry point is `main()`, exposed as the `slack-cli` console script.
|
|
- **`pyproject.toml`** — Python packaging metadata. Declares `slack-cli` console script entry point and `dfindexeddb` dependency.
|
|
- **`docs/indexeddb-format.md`** — Documents the on-disk format: LevelDB layer, IndexedDB databases, Blink value encoding, and the full Redux state schema with field-level detail.
|
|
- **`scripts/analyze_structure.py`** — Introspects the live IndexedDB and dumps database/object-store/record-type info plus Redux state key schemas. Re-run this when the data format changes and update the docs accordingly.
|
|
- **`flake.nix`** — Nix dev shell (python3.12, uv, snappy) + standalone package build. Packages pinned PyPI deps (python-snappy==0.6.1, zstd==1.5.5.1, dfindexeddb) inline.
|
|
|
|
## Dev Environment
|
|
|
|
```bash
|
|
nix develop # Enter shell with python3.12, uv, snappy
|
|
./slack-cli.py # uv resolves deps automatically via inline metadata
|
|
```
|
|
|
|
Or without nix, ensure `python3.12`, `uv`, and `libsnappy` are available.
|
|
|
|
## Building
|
|
|
|
```bash
|
|
nix build # Build standalone CLI to ./result/bin/slack-cli
|
|
nix run # Build and run directly
|
|
nix run . -- --help # Pass args
|
|
```
|
|
|
|
## Dependencies
|
|
|
|
All Python deps are declared inline in each script's `# /// script` metadata block. `uv` resolves and caches them automatically. The only dependency is:
|
|
|
|
- **`dfindexeddb`** — Forensic parser for Chromium IndexedDB/LevelDB and Blink V8 serialized values.
|
|
|
|
The nix flake provides **`snappy`** (the C library) because `python-snappy` needs it to compile its native extension.
|
|
|
|
## Important Rules
|
|
|
|
1. **Timeout for bash tool**: The `bash` tool MUST have a timeout specified.
|
|
2. **File writing**: Use the `write` / `edit` tools, not `cat` with heredocs.
|
|
3. **No PII in docs**: Documentation must contain **zero** identifying information — no real Slack IDs (user, channel, team, file, bot, group), names, emails, message content, or workspace names. Use anonymized placeholders like `U0XXXXXXXXX`, `C0XXXXXXXXX`, `T0XXXXXXXXX`, `"MyBot"`, etc. The analysis scripts read live data, but anything written to `docs/` must be scrubbed.
|
|
|
|
## Style
|
|
|
|
### Comment Style
|
|
|
|
A logical block of code should have a Title Case comment above it:
|
|
|
|
```python
|
|
# Build Channel Name Lookup
|
|
channel_names = {}
|
|
for cid, cdata in channels_store.items():
|
|
...
|
|
```
|