Files

T

paulandClaude Opus 4.8 ef57761859 feat: spotify-only matching + optional local-LLM gate + google→bandcamp fallback (closes task/drop-musicbrainz-google-fallback, closes task/ollama-classifier)

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>

2026-06-19 12:50:07 +00:00

3.8 KiB

Raw Blame History

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.

Make a small, reversible change.
Run the gate: bash scripts/check.sh (must print ALL CHECKS PASSED).
Commit citing the towl ref (e.g. (task/odesli-direct-links)), push main.
Stamp the SHA on the towl item: stamp_commit { ref, sha, repo: "linker" }.
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 " bandcamp" Google fallback.

3.8 KiB Raw Blame History

Agent rules for the linker repo (reddit → spotify/bandcamp)