paulandClaude Opus 4.8
ef57761859
Source: human-feedback note 01KVDYV3A35B57N15CRBQDXPCH (project/reddit-spotify-linker, 2026-06-18) — "remove the musicbrainz integration and just use spotify"; a google search for "<name> bandcamp" fallback; and "would a local llm be better able to categorise these ... include instructions for running something suitable via ollama (16GB M2)". - Remove MusicBrainz entirely (viaMusicBrainz + url-rels + rate-gate; lib relUrls/mbResult). Spotify is now the only music API; it both gates by exact-name match and supplies the direct artist link. - Optional ollama LLM gate (OLLAMA_URL enables it, OLLAMA_MODEL default qwen2.5:3b) called over plain HTTP -> stays zero npm-dep. It classifies which candidates are real artists/albums (the matching-quality lever). Pure prompt/parse logic in new llm.js (unit-tested in llm.test.js); the fetch + resolveAll gate wiring live in resolver.js. - A confirmed name links to its direct Spotify page when available, else a Google search for "<name> bandcamp". New "google" primary platform rendered by the extension (styles.css blue accent + platform-aware link title in content.js). - README: drop MusicBrainz; document the two gates + a runnable local-LLM setup for a 16GB MacBook M2. AGENTS.md: flip the old "no ML/NER" standing decision per the human override. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
72 lines
3.8 KiB
Markdown
72 lines
3.8 KiB
Markdown
# Agent rules for the `linker` repo (reddit → spotify/bandcamp)
|
|
|
|
A Firefox extension + a tiny Node resolver that turn artist/band names in reddit
|
|
comments into Spotify/Bandcamp links. This file is the repo-local doctrine; the work
|
|
is tracked in the **towl** work-item store under project **`reddit-spotify-linker`**.
|
|
|
|
## Stack & layout
|
|
|
|
- `service/` — zero-dependency Node resolver (Node 18+, built-in `fetch`/`http`).
|
|
`resolver.js` = the HTTP server; `lib.js` = pure, side-effect-free logic (the
|
|
artist-match precision lever) so it's unit-testable; `llm.js` = pure ollama
|
|
prompt/parse helpers (the optional local-LLM gate, HTTP-only — no in-process
|
|
model runtime); `lib.test.js` + `llm.test.js` = `node:test`. The only music API
|
|
is Spotify (MusicBrainz removed).
|
|
- `extension/` — Firefox **MV2** content script (`content.js` + `manifest.json` +
|
|
`styles.css`). No build step.
|
|
- `scripts/check.sh` — the local check gate.
|
|
|
|
## How work lands (IMPORTANT — this is NOT the towl repo)
|
|
|
|
`linker` is hosted at **git.yapplesauce.com/paul/linker**, a **plain repo**: there is
|
|
**no PR pipeline and no branch protection**. You **push to `main` directly** (via the
|
|
user's PAT). Do **not** use `towl-orchestrate` / worktree+PR here.
|
|
|
|
1. Make a small, reversible change.
|
|
2. Run the gate: `bash scripts/check.sh` (must print `ALL CHECKS PASSED`).
|
|
3. Commit citing the towl ref (e.g. `(task/odesli-direct-links)`), push `main`.
|
|
4. Stamp the SHA on the towl item: `stamp_commit { ref, sha, repo: "linker" }`.
|
|
5. Close the towl item.
|
|
|
|
**NEVER touch the `towl` or `stickball` repos from work scoped to this project.**
|
|
|
|
## Testing (zero-dep)
|
|
|
|
`node --test` over `service/*.test.js` exercises `lib.js` (norm + the exact-name match
|
|
+ link builders). Keep pure logic in `lib.js` (not `resolver.js`, which has the
|
|
server side effect) so it stays testable without opening a port. **Add/extend a test
|
|
with every logic change.** The extension's in-browser behavior is **not** headlessly
|
|
testable in this environment — validate `content.js` with `node --check` and a
|
|
documented manual check on a real reddit thread (`about:debugging` → load temporary
|
|
add-on).
|
|
|
|
## Code stewards (towl plans under objective/linker-stewardship)
|
|
|
|
Standing, language-appropriate stewards (adapted from towl's SCOUT→FILE doctrine; run
|
|
them like any other steward — e.g. via a `/loop`). Each files findings into towl and
|
|
fixes small things directly.
|
|
|
|
- **quality** (`plan/steward-linker-quality`) — correctness + regressions; **owns and
|
|
maintains `scripts/check.sh` and the `node:test` suite**.
|
|
- **design** (`plan/steward-linker-design`) — detection precision/recall, the
|
|
injected-link UX, README accuracy, reddit-DOM drift.
|
|
- **security** (`plan/steward-linker-security`) — DOM injection (build nodes via
|
|
`createElement`/`textContent`, **never `innerHTML`**; http(s) hrefs only), minimal
|
|
extension permissions, bounded external API calls (no SSRF), secrets never
|
|
logged/committed (`.env` is gitignored).
|
|
|
|
## Standing decisions
|
|
|
|
- Firefox **MV2** stays — Mozilla has no deprecation timeline; do not migrate to MV3
|
|
speculatively.
|
|
- **Optional local LLM is the recommended better-matching path** (human override,
|
|
feedback 2026-06-18 — supersedes the old "no ML/NER" rule). The resolver may call
|
|
ollama over HTTP (`OLLAMA_URL` enables it, `OLLAMA_MODEL` defaults `qwen2.5:3b`)
|
|
to classify which candidates are real artists/albums. It stays **zero-NPM-dep**:
|
|
HTTP only, no in-process model runtime. The heuristic + Spotify exact-match is the
|
|
zero-dep default when no LLM is configured.
|
|
- Detection precision lever (zero-dep default): a candidate links **only** when
|
|
Spotify returns an artist whose name matches it case-insensitively. A confirmed
|
|
name links to its Spotify artist page if available, else a "<name> bandcamp"
|
|
Google fallback.
|