AGENTS.md · diff
git:20260422.17de0e5 to git:20260427.1cadb40
3 added, 73 removed. Audit A to A.
# Awesome Pi coding agent
This is a Typescript (Bun) project that automatically discovers, enriches, and renders a curated list of resources for the [Pi Coding Agent](https://pi.dev/) ecosystem into an awesome-list README.
- ## Pipeline Architecture
-
- The project is a **three-stage data pipeline** (`discover → enrich → generate`) driven by CLI commands in `src/index.ts`. A fourth `prune` command cleans stale data.
-
- ```
- Data Sources Pipeline Stages Output
- ───────────── ───────────────── ──────────
- npm registry ──┐
- GitHub Search ──┤ ┌──────────────┐
- YouTube API ──┘───▶│ DISCOVER │ Find candidates via search APIs
- │ src/discover/│ Dedup by URL/ID, filter irrelevant
- └──────┬───────┘
- │
- ┌──────▼───────┐
- │ ENRICH │ GitHub metadata (stars, commits, license)
- │ src/enrich/ │ README analysis → category classification
- └──────┬───────┘ Health scoring (active/maintained/stale/dead)
- │
- ┌──────▼───────┐
- │ GENERATE │ Renders README.md with sorted tables
- │ src/generate/│ per category (extension/tool/theme/...)
- └──────────────┘
- ```
-
- ### Key Concepts
-
- - **Identity Model**: npm package name is the canonical ID. GitHub-sourced entries use `owner-repo`. YouTube entries use `YT_<videoId>`.
- - **Storage**: File-per-entry JSON under `data/<category>s/` (e.g. `data/extensions/pi-mcp.json`). Scoped npm packages stored as `@scope--name.json`.
- - **Categories**: extension, tool, theme, provider, template, video, example, documentation
- - **Health**: Score 0–100 mapped to active (≥70), maintained (≥40), stale (≥15), dead (<15)
- - **Filtering**: Relevance filter rejects Raspberry Pi / unrelated matches. Blacklist (`data/blacklist.json`) handles edge cases.
- - **Caching**: `.cache/` directory with 1h TTL for API responses (`src/lib/cache.ts`)
- - **Dedup**: npm wins over GitHub (npm ID kept, GitHub URL stored in metadata). Cross-referenced by `metadata.github_url`.
-
- ### Source Layout
-
- ```
- src/
- index.ts CLI entry point (discover/enrich/generate/pipeline/prune/blacklist)
- discover/ Stage 1: Find candidates
- index.ts Discoverer interface + QueryDiscoverer base class
- npm.ts npm registry search (primary source)
- github.ts GitHub Search API (secondary)
- youtube.ts YouTube Data API
- filter.ts Relevance filtering (Raspberry Pi rejection, etc.)
- enrich/ Stage 2: Add metadata
- index.ts Orchestrator (dedup, batch process, concurrency=5)
- classify.ts Rule-based category classifier
- github-meta.ts Fetch stars/forks/license/activity from GitHub API
- readme.ts Fetch + analyze READMEs for category hints
- health.ts Health scoring (GitHub-based & YouTube-based)
- videos.ts Enrich video titles/thumbnails via noembed.com
- generate/ Stage 3: Render output
- readme.ts Awesome-list README.md generator
- site.ts (future: static site)
- lib/
- store.ts File-per-entry data access layer
- types.ts Core types (Entry, CategorizedEntry, DiscoveryCandidate, ...)
- cache.ts File-based TTL cache for API responses
- github.ts GitHub REST API client (native fetch)
- ```
-
- ### Commands
-
- | Command | Description |
- |---------|-------------|
- | `bun run discover` | Run all discovery pipelines (GitHub, npm, YouTube) |
- | `bun run enrich` | Enrich entries with metadata, classify, score health |
- | `bun run generate` | Regenerate README.md from entry data |
- | `bun run pipeline` | Full pipeline: discover → enrich → generate |
- | `bun run prune` | Remove entries that don't relate to Pi coding agent |
-
- Environment variables (see `.env.example`): `GITHUB_TOKEN` for GitHub API, `YOUTUBE_API_KEY` for YouTube discovery.
+ Currently under full rewrite, refer to docs/ARCHITECTURE.md and docs/REWRITE-PLAN.md for up to date state.
# Guidelines for coding agents
- **ALWAYS** run `bun run check` before considering a change complete and ready
+ - **ALWAYS** run `bun run format` to auto-fix lint/format issues (import ordering, etc.) before falling back to manual edits
- **ALWAYS** ensure we're using up to date latest and greates 3rd-party components
+ - **ALWAYS** update `docs/ARCHITECTURE.md` when changing the structure, modules, or design decisions of `src/`. Keep the status markers (✅ done, 🟡 in progress, 🔲 not started) accurate.