dsh-tinyfish

Every release mirrors @viztor/dsh-tinyfish to GitHub Packages — a second source if npmjs.org is unreachable, and what populates the repository sidebar. Only the scoped name mirrors: GitHub links packages to repositories by owner scope. Unlike npmjs, GitHub Packages requires authentication even for public packages: an unauthenticated request 404s without saying whether the package exists. With a token carrying read:packages:

# project-local .npmrc is better than global for a token
@viztor:registry=https://npm.pkg.github.com
//npm.pkg.github.com/:_authToken=ghp_xxx

then npm install @viztor/dsh-tinyfish resolves from the mirror. Unless npmjs is down, prefer it: no token, no extra configuration.

Everything lives in one row, dsh-tinyfish. The row is validated, so an out-of-range value is rejected with a message rather than silently clamped.

Turning one off reports unavailable rather than missing — the harness tells those apart, and only the second means "the install is broken". But unavailable is not a silent fall-through: if searchProvider/fetchProvider still names TinyFish, the call fails. Point that tool at another provider to use one.

Manifest metadata, not configuration

The manifest also carries dsh.compatibility: the Node and DSH ranges stated explicitly, plus a per-release verdict — compatible, incompatible, or unknown — for the DSH versions a catalog checks.

DSH itself never reads it. Neither compatibility nor dshReleases appears anywhere in the harness, so these fields cannot change how the plugin loads, registers, or behaves. They exist so a listing can state what has actually been verified, and the verdicts here are honest rather than aspirational: 0.2.0-rc.2 is what every build and test in this repository runs against, 0.2.0-rc.1 is admitted by the peer range but never exercised, and 0.1.7-rc.2 sits below that floor.

- id: dsh-tinyfish
  config:
    search: true
    fetch: false # TinyFish stays registered but unavailable for fetch; point fetchProvider elsewhere to use another fetch

Filters live in the patch file

filters is a nested object, and the settings form addresses one flat key per field — so search tuning stays operator-level:

- id: dsh-tinyfish
  config:
    channel: monid
    filters:
      domainType: research_paper
      language: zh
      includeDomains: arxiv.org,openreview.net

Where a credential comes from

Resolved per call — a rotated key takes effect on the next search, no restart. First match wins:

1. the apiKey literal in the row (a secret in config; prefer 2–3)
2. the credentials service — apiKeyEnv (direct) or monidKeyEnv (monid), saved from the settings UI
3. the launch environment (exported before DSH started)
4. the live environment (MONID_API_KEY / TINYFISH_API_KEY)
5. the channel's CLI store (monid keys add / tinyfish auth login)

A failing service falls through to the next source rather than failing the search.

Where an endpoint comes from

Row, then environment, then built-in default — so staging can retarget without a patch:

• A 404 is a result, not an error. A per-URL fetch failure comes back carrying its status, because that is resource state the model needs.
• publishedAt is honest. TinyFish reports human dates ("Apr 30, 2026", "1 year ago"). What parses becomes ISO-8601; what doesn't is dropped, never invented. Unzoned dates read as UTC, so the same page reports the same day everywhere.
• Empty searches retry. The upstream answers a valid query with nothing about one run in three — a blank result is retried up to attempts before it is believed.
• A blocked run is terminal. If a Monid workspace control stops a run, the error says why and links to top up. Never retried.
• Off means unavailable, not gone. A switched-off kind stays registered and declines. If the profile still pins that tool to Tinyfish, the call fails loudly instead of silently rerouting — point the tool at another provider to use one. With nothing pinned, a withdrawn Tinyfish simply yields: auto-select picks whoever is left, and switching one kind off is how you resolve an "ambiguous provider" standoff down to a single candidate.
• Unavailable has three causes and one message. The seam only sees a boolean, so "switched off", "no credential", and "bad base URL" all read the same downstream. The card can tell them apart — check the switches, the key badges, and the endpoint overrides there.
• purpose is one sentence for every fetch. The seam's fetch request carries a URL and nothing else — no goal slot, by design — so a per-call goal is impossible without a harness change. The configured sentence is attached to each fetch verbatim: a standing bias, not a per-task instruction.

TinyFish's agent and browser surfaces are not exposed: metered, wallet-billed, and not a search or a fetch. Use the tinyfish CLI directly when a page genuinely needs a real browser.

The toolchain is Vite+: vp pack builds with tsdown, vp test runs Vitest, vp lint / vp fmt are Oxlint and Oxfmt, type-aware. Lint and format live in vite.config.ts — Vite+ ignores standalone configs.

pnpm install
pnpm test               # hermetic — no network, no credential
pnpm run check          # format + lint + types
pnpm run release:gate   # build, then the full gate incl. 18 package checks
pnpm run test:live      # the real APIs, still $0, needs credentials

Requires DSH ^0.2.0-rc.1 (0.2.0-rc.1 and later, below 0.3.0) and Node 24+. Full process and invariants: AGENTS.md. Contributing: CONTRIBUTING.md.