opensrc git:20260728.3aaa44bA

Immutable. This exact content is served forever at /api/v1/blob/b9b9658d8eb82aef.

---
name: opensrc
description: "Inspect dependency and upstream source with the opensrc CLI. Use for package internals, exact source paths, version diffs and upgrade audits across npm, PyPI, crates and git repos. Not for general web search or release notes alone."
allowed-tools: Bash(opensrc:*)
---

# Opensrc

Use this skill when source-level dependency inspection materially changes the
answer. Prefer docs and types first; pull source when behavior, migration risk,
or implementation details matter.

## Core Workflow

1. Read the repo `AGENTS.md` and inspect relevant manifests and lockfiles.
2. Use the global `opensrc` binary. Fall back to `bunx opensrc` only if the
   binary is unavailable.
3. Use `opensrc fetch` when the goal is cache-only prep:
   ```bash
   opensrc fetch --cwd <repo-root> zod react next
   opensrc fetch <pkg>@<current_version> <pkg>@<target_version>
   ```
4. Use `opensrc path` when the next command needs a filesystem path:
   ```bash
   rg "pattern" "$(opensrc path zod)"
   cat "$(opensrc path zod)"/src/types.ts
   find "$(opensrc path pypi:requests)" -name "*.py"
   git diff --no-index "$(opensrc path <pkg>@<current>)" "$(opensrc path <pkg>@<target>)"
   ```
5. Cite exact versions and local source paths when source evidence affects the
   recommendation.
6. Use web/docs sources for release notes, API references, changelogs, and
   migration guides; use `opensrc` for implementation internals and source
   diffs.

## Version Guardrails

- `opensrc` 0.7.x caches globally at `~/.opensrc/`; `OPENSRC_HOME` overrides it.
- The cache key includes the resolved package version or repo ref. The main risk
  is incorrect version resolution before fetch, not the global cache itself.
- For npm packages, current upstream resolution checks `node_modules`, then
  `package-lock.json`, `pnpm-lock.yaml`, `yarn.lock`, then `package.json`.
- In Bun or workspace repos, use the workspace root as `--cwd` by default. If
  `node_modules` may be stale, pin versions explicitly.
- For upgrade work or ambiguity, inspect pinned versions:
  ```bash
  opensrc path pkg@current_version
  opensrc path pkg@target_version
  ```

## Supported Specs

- npm: `zod`, `npm:zod`
- PyPI: `pypi:requests`, `pip:requests`, `python:requests`
- crates.io: `crates:serde`, `cargo:serde`, `rust:serde`
- repos: `owner/repo`, `github:owner/repo`, `gitlab:owner/repo`,
  `bitbucket:owner/repo`, or full URLs
- pinned refs: `pkg@version`, `owner/repo@tag`, `owner/repo#branch`
- private repo auth: `GITHUB_TOKEN`, `GITLAB_TOKEN`, `BITBUCKET_TOKEN`

## Upgrade Audits

Compare current and target with official docs plus pinned source paths.
Prefer package-native capabilities, delete obsolete wrappers/shims/adapters, and
avoid dual-shape compatibility unless a real boundary requires it.

## References

- Read `references/opensrc-cli-reference.md` for exact CLI surface, cache model,
  supported spec forms, auth env vars, and release deltas.
- Read `references/dependency-upgrade-audit.md` for package upgrade, migration,
  current-versus-target, or hard-cut audits.

## Do Not Use For

- broad web research that does not require source inspection
- release-note summaries where docs alone answer the question
- simple API usage questions that types and official docs already resolve

## Output

Include the resolved current and target versions, exact local source paths used,
and whether source inspection changed the conclusion. For upgrade work, include
a concise hard-cut migration brief and verification checklist.