Qv Holepunch Dev

Holepunch Development

Ecosystem navigator for Holepunch/Bare/Pear development. Teaches the agent to discover APIs on-the-fly rather than carrying static knowledge dumps.

Canonical Index: docs.pears.com

https://docs.pears.com is the curated, always-current index for the entire ecosystem. Prefer it over any static list in this skill. Relevant anchors:

• #p2p-modules — Building-block libraries (hypercore, hyperbee, hyperdrive, autobase, hyperdht, hyperswarm) and helpers (corestore, localdrive, mirror-drive, secret-stream, compact-encoding, protomux).
• #bare-modules — All bare-* runtime modules with stability indicators and platform support. Most are Node.js standard-library equivalents (bare-fs ≈ fs, bare-crypto ≈ crypto, bare-tcp ≈ net, bare-subprocess ≈ child_process). Node.js-compat shims live in bare-node.
• #pear-modules — pear-* modules grouped by role (Application, UI, Common, Developer, Integration). Largest surface: pear-electron (100+ methods for desktop UI — fetch its README). Lifecycle commands: pear init/run/stage/seed/release.

P2P Stack by Purpose

docs.pears.com groups P2P libraries as "building-block vs helper". This table groups by purpose and includes libraries used widely across Holepunch-based applications (Keet, PearPass/autopass, QVAC registry-server, WDK, etc.) that are not on the docs.pears.com index page:

Repo-name anomaly: @hyperswarm/secret-stream ships from the holepunchto/hyperswarm-secret-stream repo.

Discovery Playbook

When you need to learn about a Holepunch library, follow these steps in order. Do not stop at the first source if the API surface is still unclear.

Step 1: docs.pears.com

Navigation hub and canonical module index. How-to guides contain working executable examples.

• Module index: https://docs.pears.com/ (see anchors above)
• Building blocks overview: https://docs.pears.com/index.html#building-blocks
• How-tos (real code):
  • https://docs.pears.com/howto/connect-two-peers-by-key-with-hyperdht.html
  • https://docs.pears.com/howto/connect-to-many-peers-by-topic-with-hyperswarm.html
  • https://docs.pears.com/howto/replicate-and-persist-with-hypercore.html
  • https://docs.pears.com/howto/work-with-many-hypercores-using-corestore.html
  • https://docs.pears.com/howto/share-append-only-databases-with-hyperbee.html
  • https://docs.pears.com/howto/create-a-full-peer-to-peer-filesystem-with-hyperdrive.html

Step 2: GitHub README

Primary API documentation lives in README files:

gh api repos/holepunchto/{repo}/readme --jq .content | base64 -d

Step 3: Test files

Holepunch repos have excellent tests that show real usage patterns:

gh api repos/holepunchto/{repo}/contents/test
# Then fetch specific test files for usage examples

Step 4: Example repos

For higher-level integration patterns:

gh api repos/holepunchto/examples/contents

Step 5: Workshop repos

Guided tutorials for specific topics (HyperDB, Autobase multi-writer, Pear apps):

gh api "search/repositories?q=org:holepunchto+workshop+in:name" --jq '.items[] | "\(.full_name) - \(.description)"'

Known workshops: pear-workshop, hyperdb-workshop, hyperdb-autobase-workshop.

Step 6: Dependency traversal

Holepunch dependency trees are deep. When a library references another holepunch library, follow the chain:

gh api repos/holepunchto/{repo}/contents/package.json --jq .content | base64 -d \
  | jq '.dependencies // {} | keys[] | select(test("hyper|autobase|corestore|protomux|blind-|compact-encoding|b4a|ready-resource|safety-catch"))'

Recursively fetch READMEs/tests for any holepunch dependency relevant to the current task. Do not stop at the first library; trace the dependency graph until the needed API surface is understood.

Step 7: Keet repos (optional, requires access)

For bleeding-edge patterns not yet in dedicated libraries. These repos may be private; skip gracefully on 404:

gh api "search/repositories?q=org:holepunchto+keet+in:name" --jq '.items[].full_name'

Step 8: Source code

When README is insufficient, read index.js or lib/ directly:

gh api repos/holepunchto/{repo}/contents/index.js --jq .content | base64 -d
gh api repos/holepunchto/{repo}/contents/lib --jq '.[].name'

Composition Patterns

P2P KV Database (simplest)

Corestore + Hyperswarm + Hyperbee:

const store = new Corestore(storage)
const core = store.get({ name: 'my-db' })
const db = new Hyperbee(core, { keyEncoding: 'utf-8', valueEncoding: 'utf-8' })
await store.ready()

const swarm = new Hyperswarm()
swarm.on('connection', conn => store.replicate(conn))
swarm.join(core.discoveryKey)

P2P Multi-writer DB

Corestore + Hyperswarm + Autobase + HyperDB + Hyperschema + Hyperdispatch. Full schema pipeline: define schema in Hyperschema, build collections with HyperDB builder, define routes in Hyperdispatch. Autobase open() returns HyperDB.bee instance; apply() dispatches operations via router; call view.flush() after batch.