Contributing

Short version: the most useful thing you can do is add a source or fix a broken one. Everything else follows.

Where your time pays back most

Contribution	Impact	Difficulty
Add a new source adapter	High — directly expands the index	Medium
Fix a broken source adapter	High — silent breakage is our main failure mode	Low–Medium
Improve metadata mapping on an existing adapter	High — better artist / date / medium surfaces more useful results	Low
Report a broken source with repro steps	High — lets maintainers fix fast	Very low
Translate the UI into a new language or improve a generated locale	Medium — reaches a new user base	Low
Fix a bug labelled bug in the issue tracker	Medium	Varies
Improve docs (this site)	Medium — typos, missing context, unclear wording	Low
Propose a feature	Medium — but only with a use case, see Roadmap	Low

Development setup

git clone https://github.com/GI-Synth/InspoSearch.git
cd InspoSearch
npm install        # only devDependencies — the app itself has zero runtime deps
npm run build      # bundles src/ → insposearch/app.js + builds docs
npm start          # serves insposearch/ at http://localhost:3000

Useful during iteration:

npm run build:watch   # rebuild on save
npm run build:app     # skip the docs build (faster)
npm test              # vitest unit tests
npm run test:e2e      # Playwright e2e (requires prior build)
npm run lint
npm run validate      # validate source manifests — same check CI runs

To exercise a single adapter end-to-end:

node scripts/test-source.js <sourceName>

Repo layout

src/                ES modules — edit these
  state.js          constants, source registry, query classification
  core.js           health tracking, session cache, safeFetch, scoring
  fetchers.js       100+ source adapters + keyword expansion
  app.js            search orchestration, rendering, DOM events, AI
  i18n.js           6 base locales + 95 generated
  main.js           esbuild entry point
insposearch/        static site (served by Cloudflare Pages)
  app.js            minified bundle output — never edit directly
  sources/          community source manifests (*.json)
  data/             pre-fetched data for CORS-blocked sources
  docs/             VitePress build output (generated)
api/                Cloudflare Workers
  worker.js         REST API (/search, /sources, /random, /health, …)
  image-proxy.js    thumbnail CORS proxy
scripts/            build + maintenance utilities
INSPOSEARCH.DOCS/   VitePress docs source (edit here for doc changes)
tests/              vitest unit tests + Playwright e2e

Code style

• Vanilla JS — no frameworks, no runtime npm dependencies in the app bundle
• ES modules throughout (import / export)
• DM Mono for UI text, Cormorant Garamond for headings and the logo
• Dark-first — design for dark backgrounds; light mode is derived
• Single quotes for strings, const by default
• Never font-weight above 400, never border-radius
• Comments only when the why is non-obvious — well-named identifiers cover the what

Commit messages

Conventional Commits:

feat(sources): add National Diet Library
fix(search): prevent duplicate results on rapid Enter
perf(search): reset source health on every new query
docs: clarify API key storage in api-keys.md

Scope is optional but useful. Prefer small, single-purpose commits.

Pull request process

1. Fork and create a branch: git checkout -b <type>/<short-description> (e.g. source/national-diet-library)
2. Make the change in small, focused commits
3. Run npm test, npm run lint, and npm run validate locally
4. For UI changes, test in a browser — type checking and unit tests don't catch visual regressions
5. For new sources, run the 3-term test protocol and attach screenshots
6. Open a PR against main with a description that says what changed and why
7. CI will run validation and tests; address any failures before asking for review

PR checklist

• [ ] Descriptive title in Conventional Commits format
• [ ] One concern per PR — don't bundle unrelated changes
• [ ] Screenshots for anything visual
• [ ] Source additions include the 3-term test evidence
• [ ] No API keys or secrets committed
• [ ] Docs updated if behaviour changed (INSPOSEARCH.DOCS/docs/)
• [ ] No unexplained node_modules/ or build artefacts

Reporting bugs

A good bug report includes:

• Browser + version, OS
• Exact search query (copy-pasted, not paraphrased)
• What you expected vs. what happened
• Browser console errors (Ctrl+Shift+J / Cmd+Opt+J)
• Screenshot or short screen recording for UI issues
• Source name if the bug is source-specific

Open an issue →

Reporting a broken source

Use the broken-source label and include:

• Source name exactly as it appears in the Sources sidebar
• Search query that surfaced the issue
• Any console error from the Network tab for that source's request
• Whether it fails for all queries or just some

Security

Responsible disclosure: email insposearch.engine@gmail.com rather than filing a public issue.

Licence

InspoSearch is AGPL-3.0-only. Contributions are licensed under the same terms. If you run a modified version over a network, the AGPL network-use clause applies — see the License page.