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:

   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:

   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:

  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

For npm/Bun dependency upgrades, if this helper exists, use it as the fast inventory layer before deeper source reasoning:

deps-workbench upgrade-prep --cwd <repo-root> --package <pkg> --out <tmp.json>
deps-workbench report --input <tmp.json> --format md

Then 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.

Dependency Upgrade Audit

Use this workflow when the task is to analyze a package upgrade deeply and produce a migration brief that enables a hard-cut integration in the host repo.

Goal

Compare the repo's current dependency version against a target or latest version using:

• official docs and API references
• release notes and changelogs
• upstream source for both versions
• a deep audit of how the host repo currently uses the package

The output should make it obvious what to change, what to delete, and what new native package capabilities should replace repo-owned code.

Workflow

If /home/bjorn/.codex/skill-support/bin/deps-workbench exists and the package is in the Bun/npm lane, start with:

tmp_json="$(mktemp)"
deps-workbench upgrade-prep --cwd <repo-root> --package <pkg> --out "$tmp_json"
deps-workbench report --input "$tmp_json" --format md

Use that output as the fast inventory layer, then continue with the deeper source, docs, and migration reasoning below.

1. Establish Current Repo State

1. Read the repo's manifests and lockfiles. 2. Identify the currently declared version. 3. Resolve the current source with:

opensrc path <pkg> --cwd <repo-root>

4. Verify the returned version from the path or metadata. 5. In Bun repos, assume stale node_modules can mislead resolution. If there is any ambiguity, pin explicitly instead of trusting auto-detect.

2. Establish Target State

1. Identify the target version or latest release from official sources. 2. Read the package's:

• docs
• changelog
• release notes
• migration guide
• API reference

3. If the package lives in a monorepo, locate the real package subtree before comparing source.

3. Fetch Both Source Trees Explicitly

Always pin both versions for upgrade analysis.

opensrc fetch <pkg>@<current_version> <pkg>@<target_version>
opensrc path <pkg>@<current_version>
opensrc path <pkg>@<target_version>

If you do not need cache warmup as a separate step, opensrc path alone is still sufficient because it fetches on cache miss.

For repos:

opensrc fetch owner/repo@tag owner/repo#branch
opensrc path owner/repo@tag
opensrc path owner/repo#branch

4. Diff and Inspect the Upstream Source

Use direct tree and file comparison:

git diff --no-index "$(opensrc path <pkg>@<current>)" "$(opensrc path <pkg>@<target>)"

Then inspect surgically with:

• rg for renamed or removed APIs
• direct file reads for changed entrypoints
• tests to infer behavioral changes
• README/docs in the source tree to cross-check declared behavior

Look for:

• removed exports
• renamed imports
• changed configuration shapes
• new runtime requirements
• deprecated APIs
• moved package entrypoints
• newly added package-native capabilities

Host Repo Audit

Search the host repo for all package touchpoints:

• imports
• wrappers
• config files
• adapters
• polyfills
• custom code that overlaps with package capabilities
• tests that encode now-obsolete package behavior

Ask:

• What custom repo code exists only because the older package lacked a feature?
• What package-native capability now replaces that custom code?
• What deprecated or removed APIs are still in use?
• What compatibility branches can be deleted in a hard-cut migration?

Hard-Cut Rules

Default to one canonical target shape.

• Prefer package-native capabilities over repo-owned custom code.
• Delete obsolete wrappers, shims, adapters, and compatibility helpers.
• Do not preserve dual-shape integrations unless there is a real external

boundary that requires it.

• Update tests and fixtures to the new canonical package behavior only.
• If a real compatibility boundary exists, name the exact file and reason.

Required Output Format

Return a concise report with these sections:

Current and Target

• current declared version
• current resolved source version
• target version
• exact source paths used

Sources Consulted

• official docs
• changelog or release notes
• upstream source paths
• host repo files searched

Breaking or Material Changes

• removed or changed APIs
• behavior changes
• config or runtime changes
• migration-sensitive edge cases

New Capabilities to Adopt

List package-native capabilities in the target version that should replace custom repo code or reduce maintenance.

Obsolete Repo Code to Delete

Call out wrappers, helpers, adapters, or legacy config that should be removed in a hard-cut integration.

Required Changes

• import changes
• config changes
• runtime changes
• test updates
• docs updates

Migration Checklist

Provide a short, actionable checklist for implementing the upgrade.

Verification Checklist

List the commands or checks needed to prove the migration is complete.

Unknowns

Mark anything that could not be confirmed as UNVERIFIED.

Operating Notes

• Prefer the repo root for --cwd in workspaces.
• In Bun repos, explicitly verify resolved versions before analysis.
• Use opensrc for code, not as a substitute for official migration docs.
• If latest is risky or unstable, compare current against the exact intended

target version instead of defaulting to latest.

• Do not over-automate the final migration decision. The helper is for prep, not

for replacing source interpretation, API review, or hard-cut reasoning.

Opensrc CLI Reference

This file captures the current opensrc 0.7.x command surface and the cache model that replaced the older project-local workflow.

Canonical Baseline

• Local binary verified in this session: opensrc 0.7.2
• Architectural cutover: v0.7.0
• Current patch baseline: v0.7.2

Command Surface

opensrc fetch

Cache-prewarm command. Use when you want sources downloaded without printing paths.

opensrc fetch zod
opensrc fetch --cwd /path/to/project zod react next
opensrc fetch <pkg>@<current_version> <pkg>@<target_version>
opensrc fetch bitbucket:workspace/private-repo

Options:

• --cwd <path>: working directory for lockfile version resolution
• --quiet / -q: suppress progress output

opensrc path

Primary composition command. Prints the absolute path to source and fetches on cache miss.

opensrc path zod
opensrc path pypi:requests
opensrc path crates:serde
opensrc path vercel/next.js

rg "parse" $(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_version>)" "$(opensrc path <pkg>@<target_version>)"

Options:

• --cwd <path>: working directory for lockfile version resolution
• --verbose: show fetch progress

Multiple specs print one path per line:

opensrc path zod react next
opensrc path pypi:requests pypi:flask
opensrc path crates:serde crates:tokio

opensrc list

Lists the global cache index.

opensrc list
opensrc list --json

opensrc remove

Removes one or more cached entries. rm is an alias.

opensrc remove zod
opensrc remove pypi:requests
opensrc remove vercel/ai
opensrc rm github:owner/repo

opensrc clean

Removes cache contents by category.

opensrc clean
opensrc clean --packages
opensrc clean --repos
opensrc clean --npm
opensrc clean --pypi
opensrc clean --crates

Supported Spec Forms

Documented/current forms:

• npm: zod
• npm alias: npm:zod
• PyPI: pypi:requests
• PyPI aliases: pip:requests, python:requests
• crates.io: crates:serde
• crates.io aliases: cargo:serde, rust:serde
• GitHub shorthand: owner/repo
• explicit hosts: github:owner/repo, gitlab:owner/repo, bitbucket:owner/repo
• full repo URLs
• package version pins: zod@4.3.6, pypi:flask@3.0.0
• repo refs: owner/repo@v1.0.0, owner/repo#main

Cache Model

opensrc 0.7.x uses a global cache, not a project-local opensrc/ folder.

Default root:

~/.opensrc/

Override:

export OPENSRC_HOME=/custom/cache/path

Typical layout:

~/.opensrc/
├── repos/
│   └── github.com/
│       └── owner/
│           └── repo/
│               └── version-or-ref/
└── sources.json

The cache key includes the resolved version or ref. Different repos can safely use different cached versions at the same time.

Version Resolution

Upstream code currently resolves npm-family package versions in this order:

1. node_modules/<pkg>/package.json 2. package-lock.json 3. pnpm-lock.yaml 4. yarn.lock 5. package.json

Implications:

• The main failure mode is stale local install state, not the global cache.
• In Bun repos, stale node_modules can win before any lockfile parsing.
• Use the repo root as --cwd by default in workspaces.
• Verify the returned path/version before trusting the result.
• For upgrade or migration work, pin both versions explicitly.

Documented vs Observed

Documented:

• npm lockfile and install detection only mention node_modules,

package-lock.json, pnpm-lock.yaml, yarn.lock, and package.json.

Observed in upstream v0.7.2 source:

• version resolution was substantially rewritten for pnpm workspaces and Yarn

workspace/protocol edge cases

• transitive pnpm resolution now has dedicated fixture coverage
• workspace/link/file/git protocol specs are explicitly filtered so they do not

get treated as registry versions

Observed in this session:

• opensrc path react --cwd /home/bjorn/repos/signr resolved 19.2.0
• opensrc path zod --cwd /home/bjorn/repos/signr resolved 4.3.6

Interpretation:

• opensrc can still work correctly in Bun workspaces when node_modules is

current.

• Do not claim documented bun.lock support unless upstream docs/code say so.

Auth and Environment

Current repo-auth environment variables:

• GITHUB_TOKEN
• GITLAB_TOKEN
• BITBUCKET_TOKEN
• OPENSRC_HOME

Do not use the older provider-specific legacy token variable names from the pre-0.7 workflow.

Release Deltas That Matter

v0.7.0

• Rust rewrite with native binary
• global cache at ~/.opensrc/
• opensrc path as the primary command
• docs site added at opensrc.sh
• repo reorganized into CLI plus docs monorepo
• cross-platform binary releases

v0.7.1

• private repo support documented around standard GITHUB_TOKEN and

GITLAB_TOKEN

• remove accepts the same repo formats as the fetch/path-facing specs

v0.7.2

• dedicated opensrc fetch subcommand for cache-only workflows
• Bitbucket Cloud repo support plus BITBUCKET_TOKEN
• auth docs page covering GitHub, GitLab, and Bitbucket tokens
• pnpm workspace and transitive lockfile parser rewrite
• Yarn workspace/protocol edge-case coverage
• upstream official skill moved to top-level skills/opensrc/

Operational Rules

• Prefer opensrc path when the next step composes the resolved path with shell

tools.

• Prefer opensrc fetch when you only need the cache primed for CI, scripts,

or multi-version prep.

• Prefer direct opensrc invocation. Use bunx opensrc only as a fallback.
• For current-versus-target analysis, pin both versions explicitly. Optional:

prewarm with opensrc fetch <pkg>@<current> <pkg>@<target> before diffing.

• Use web/docs sources for official changelogs and API contracts.
• Use opensrc for implementation internals and tree diffs.
• Do not claim documented bun.lock support unless upstream docs/code say so.