troedler AGENTS.md

AGENTS.md — troedler

Operating guide for AI agents in the troedler repo. Follows the agents.md convention; human overview in README.md. This repo is a submodule of werkstatt, whose AGENTS.md carries the broader workspace rules — this file is the troedler-specific layer and wins where they differ.

What this is

Search several second-hand marketplaces with one query, as a CLI and an MCP server. A TypeScript monorepo that runs on GJS via gjsify (not Node), following the postbote pattern: pure-TS packages/* plus one app workspace that carries the gjsify toolchain and picks a frontend at the yargs entrypoint. A native GNOME/Adwaita GUI is planned and the seams are already cut for it.

v1 is read-only towards every marketplace. No account, no login, no listing, no bidding, no messaging. It reads what is public and tells you what it found.

Leitplanken (hard rules)

These are not style. Each one is the reason some part of the code looks the way it does, and removing one silently changes what this project is.

|Local, per user, never central. No hosted crawler, no shared index, no server endpoint, no pooling of other people's searches. That is the line between local multi-marketplace software (BGH I ZR 159/10, permitted) and a hosted meta-search engine (CJEU C-202/12 Innoweb, prohibited). It is why the MCP server speaks stdio and there is no HTTP transport. |An official API beats HTML, always. Where a marketplace offers one, the HTML path is not implemented at all — not as a fallback, not "for later". |robots.txt is a gate, not a hint. Parsed per host, cached, checked before every request in @troedler/http. Crawl-delay honoured, otherwise ≥2 s and one connection per host. Never build a URL the gate would refuse: a disallowed filter path is not a feature that unfortunately blocks, it is the thing the operator forbade. |Never logged in. No cookie jar, no session handling, no account. Without registration there is no contract of use to breach; with a login, every clause applies. |Never circumvent. No browser user-agent spoofing, no captcha/Cloudflare/Akamai/TLS-fingerprint bypass, no proxy rotation, no retry with altered headers. 403 and 429 end the attempt with a plain-language error. A refusal is a decision, not a hiccup. |Never reverse-engineered credentials. No tokens or keys extracted from apps or binaries, no private endpoints behind auth. This is the one line here with criminal exposure (§ 202a StGB, Modern-Solution line of cases through BVerfG 2025) and it is not close to the edge. |Cache is query-scoped TTL, never a mirror. Only queries a user actually made. No paging through a catalogue, no building a local picture of a market. eBay listing data: ≤6 h by licence. |Personal data is filtered while parsing, not cleaned up later. No seller names or ids, no profiles, no histories; phone numbers and e-mail addresses stripped from free text at the parser. Images are URLs — never downloaded, never rehosted. |Honest user agent, troedler/<version> (+repo-url), with a reachable contact. No spoofing. It is also how an operator who objects can reach us at all. |OPT_OUT_HOSTS in @troedler/compliance is binding. A host that objects is refused by the gate and removed in the next release. |A new source means a source record first. docs/quellen/<host>.md — robots.txt findings, the terms clause quoted, whether an API exists, bot protection, date checked — then an entry in SOURCES, then the adapter. No adapter without one. |Fixtures are synthetic. Never commit a real listing, page capture, or database. Measure against live pages locally; commit only HTML you wrote yourself.