opensrc

v0.6.0 · TypeScript · Apache-2.0 · vercel-labs/opensrc

1 — 概要

AI エージェントの文脈を型定義の先へ

opensrc は、npm / PyPI / crates.io パッケージや GitHub リポジトリのソースコードをローカルにフェッチする CLI ツール。型定義やドキュメントだけでは足りないとき、AI コーディングエージェントに実装の「中身」を直接参照させることができる。

npmデフォルト対応

PyPIpypi: プレフィックス

cratescrates: プレフィックス

GitHubowner/repo 記法

ロックファイル（package-lock.json、pnpm-lock.yaml、yarn.lock）を自動検出して正確なバージョンのタグで clone する。再実行すると更新バージョンに自動で合わせ直す。

なぜ必要か

型と JSDoc だけでは、LLM が「実際にどう動くか」を推測する精度に限界がある。opensrc zod を一度実行すると opensrc/zod/ にソースが置かれ、AGENTS.md にパスが記録される。エージェントはそこを読んで実装ベースの回答を返せるようになる。

2 — インストール

グローバルインストール

npm install -g opensrc
# または npx で都度実行
npx opensrc zod

Node.js 18 以上が必要。pnpm add -g opensrc / yarn global add opensrc でも動作する。

クイックスタート

opensrc zod → バージョン検出 → git clone (タグ) → opensrc/zod/ 生成 → AGENTS.md 更新

# 複数パッケージを一度に取得
opensrc react react-dom next

# バージョン固定
opensrc zod@3.22.0

# 再実行でロックファイルのバージョンに追従（フラグ不要）
opensrc zod

3 — コマンド一覧

サブコマンド

コマンド	エイリアス	説明
`opensrc <packages...>`	—	パッケージ / リポジトリのソースをフェッチ（デフォルト）
`opensrc list`	—	フェッチ済みソースの一覧を表示
`opensrc remove <packages...>`	`rm`	指定パッケージのソースを削除
`opensrc clean`	—	全ソース（またはフィルタ指定）を一括削除

fetch / デフォルトコマンドのオプション

オプション	説明
`--cwd <path>`	作業ディレクトリを指定（デフォルト: カレント）
`--modify`	`.gitignore` / `tsconfig.json` / `AGENTS.md` の修正を許可
`--modify=false`	ファイル修正を拒否し設定を永続化

clean のオプション

フラグ	効果
`--packages`	全レジストリのパッケージソースを削除
`--repos`	Git リポジトリソースのみ削除
`--npm` / `--pypi` / `--crates`	レジストリを絞って削除
`--cwd <path>`	作業ディレクトリを指定

list のオプション

フラグ	効果
`--json`	JSON 形式で出力（スクリプト連携向け）
`--cwd <path>`	作業ディレクトリを指定

4 — 対応ソース

レジストリプレフィックス

プレフィックス	レジストリ	例
（なし）	npm（デフォルト）	`opensrc zod`
`npm:`	npm 明示	`opensrc npm:zod`
`pypi:` / `pip:` / `python:`	PyPI	`opensrc pypi:requests`
`crates:` / `cargo:` / `rust:`	crates.io	`opensrc crates:serde`

GitHub リポジトリ記法

記法	例
`owner/repo`	`opensrc facebook/react`
`github:owner/repo`	`opensrc github:colinhacks/zod`
完全な GitHub URL	`opensrc https://github.com/colinhacks/zod`
タグ / バージョン指定 `@`	`opensrc owner/repo@v1.0.0`
ブランチ指定 `#`	`opensrc owner/repo#main`

保存パス: GitHub リポジトリは opensrc/owner--repo/ に格納される（スラッシュを -- に置換）。削除は opensrc remove owner--repo。

バージョン検出の優先順位

パッケージのバージョンは以下の順序で解決される。

node_modules/<pkg>/package.json の version フィールド
package-lock.json の packages または dependencies
pnpm-lock.yaml
yarn.lock
指定なしの場合は最新版（registry の latest dist-tag）

5 — ファイル修正

初回実行時のプロンプト

初回フェッチ時、以下 3 ファイルへの修正権限をインタラクティブに確認する。選択は opensrc/settings.json に保存され、以後は再確認しない。

対象ファイル	変更内容	目的
`.gitignore`	`opensrc/` を無視リストに追加	ソースコードの誤コミットを防止
`tsconfig.json`	`exclude` に `opensrc/` を追加	型チェック・ビルド対象から除外
`AGENTS.md`	フェッチ済みソースへのパスを記載したセクションを追記	エージェントが参照可能なソースを把握できる

--modify フラグ

プロンプトをスキップして権限を強制設定できる。CI や自動化スクリプトで有用。

# 常に修正を許可（設定を永続化）
opensrc zod --modify

# 常に修正を拒否（設定を永続化）
opensrc zod --modify=false

6 — 処理フロー

フェッチパイプライン

flowchart TD A["opensrc pkg"] --> B{"パッケージ\nor リポジトリ?"} B -->|"npm / pypi / crates"| C["レジストリ API 照会"] B -->|"github / owner/repo"| D["リポジトリ仕様パース"] C --> E["ロックファイルから\nバージョン検出"] E --> F["git タグ解決"] D --> G["ref / ブランチ解決"] F --> H["simple-git で clone"] G --> H H --> I["opensrc/pkg/ に格納"] I --> J{"ファイル修正\n権限あり?"} J -->|"あり"| K[".gitignore\ntsconfig.json\nAGENTS.md 更新"] J -->|"なし"| L["完了"] K --> L

ソースコード構成

src/
├── index.ts          # CLI エントリ。Commander.js でサブコマンドを登録
├── types.ts          # Registry / PackageSpec / FetchResult 等の型定義
├── commands/
│   ├── fetch.ts      # デフォルトコマンド。権限確認・並行フェッチ
│   ├── list.ts       # sources.json を読んで表示
│   ├── remove.ts     # opensrc/pkg/ を削除し sources.json を更新
│   └── clean.ts      # フィルタ付き一括削除
└── lib/
    ├── git.ts            # simple-git ラッパー。clone / タグ解決
    ├── version.ts        # lockfile / node_modules からバージョン検出
    ├── agents.ts         # AGENTS.md 読み書き・パッケージ索引管理
    ├── gitignore.ts      # .gitignore への opensrc/ 追記
    ├── tsconfig.ts       # tsconfig.json の exclude 更新
    ├── settings.ts       # settings.json 永続化
    ├── repo.ts           # GitHub URL パーサー・リポジトリ仕様解決
    ├── prompt.ts         # ターミナル yes/no プロンプト
    └── registries/
        ├── index.ts      # プレフィックス検出・ディスパッチ
        ├── npm.ts        # npm registry API → ResolvedPackage
        ├── pypi.ts       # PyPI JSON API → ResolvedPackage
        └── crates.ts     # crates.io API → ResolvedPackage

7 — 出力構造

ディレクトリレイアウト

opensrc/
├── settings.json       # allowFileModifications の永続設定
├── sources.json        # フェッチ済みパッケージ・リポジトリの索引
├── zod/                # npm: zod のソース
│   ├── src/
│   ├── package.json
│   └── ...
└── facebook--react/    # GitHub: facebook/react のソース (/ → --)
    ├── packages/
    └── ...

sources.json フォーマット

{
  "packages": [
    {
      "name": "zod",
      "version": "3.22.0",
      "path": "opensrc/zod",
      "registry": "npm"
    },
    {
      "name": "requests",
      "version": "2.32.0",
      "path": "opensrc/requests",
      "registry": "pypi"
    }
  ],
  "repos": [
    {
      "displayName": "facebook/react",
      "ref": "v19.0.0",
      "path": "opensrc/facebook--react"
    }
  ]
}

エージェントはこのファイルを読んで「何のソースが利用可能か」を把握できる。AGENTS.md のセクションもこの内容を反映する。

参考リンク

GitHub: vercel-labs/opensrc — ソースリポジトリ
npm: opensrc — パッケージページ