docs(vendor): add opensrc submodule and reference analysis

[amondnet]

Summary

Add vercel-labs/opensrc as a reference-only git submodule under `vendor/opensrc/` (alongside the existing `vendor/intent/`), and document its architecture, fetch pipeline, cache layout, and design contrasts with ASK.

opensrc and ASK solve the same underlying problem ("give coding agents accurate, version-specific source for installed libraries") from opposite ends — opensrc lazily clones upstream repos into a global `~/.opensrc/` cache and asks the agent to compose `opensrc path` inside shell commands, whereas ASK pre-renders per-project markdown + Claude Code skill files. Having opensrc vendored gives us a concrete reference implementation to cross-check our resolver/source split and AGENTS.md generation against.

Changes

• Add `vendor/opensrc` git submodule pinned at upstream commit `a3b9d21` (opensrc 0.7.1)
• Add `vendor/opensrc/` entry under Monorepo Structure in `CLAUDE.md` mirroring the existing `vendor/intent/` line
• Add `.please/docs/references/opensrc.md` — full architectural analysis covering:
  • ASK ↔ opensrc design comparison table (output, cache scope, version resolution, registry coverage, runtime, agent surface)
  • Repo layout (Turborepo + pnpm workspaces, Rust CLI in `packages/opensrc/cli/`, Node shim in `bin/opensrc.js`)
  • CLI surface (`path`, `list`, `remove`, `clean`) and supported spec formats
  • Fetch pipeline walkthrough (parse → cache pre-check → npm lockfile version detection → registry resolver dispatch → shallow clone with tag fallback → atomic `sources.json` update)
  • Cache layout, atomic index write, monorepo subdirectory sharing, ref-counted removal
  • Node ↔ Rust binary shim trick (postinstall replaces npm's global symlink with a direct link to the native binary for zero-overhead startup)
  • Agent-facing AGENTS.md block contrast with ASK's ``
  • Environment variables, Rust crate dependencies, release profile
  • Things worth borrowing in ASK (atomic index write, tag fallback chain, rate-limit vs 404 hints, corrupt-index recovery) and things worth not borrowing (global cache, regex-based lockfile parsing)

Test Plan

• `git submodule status` shows `vendor/opensrc` at `a3b9d21`
• `CLAUDE.md` rendering shows the new `vendor/opensrc/` bullet under Monorepo Structure
• `.please/docs/references/opensrc.md` opens cleanly with no broken relative links to upstream files
• CI passes (no source code changed — docs + submodule only)

Notes

• Reference-only — opensrc is not consumed at build/runtime by any of our packages. Same status as `vendor/intent/`.
• Pinned to upstream default branch HEAD at the time of submodule add (currently `a3b9d21`, opensrc 0.7.1). If we want to track a tag instead, follow up with `git -C vendor/opensrc checkout v0.7.1 && git add vendor/opensrc`.

---

Summary by cubic

Vendor vercel-labs/opensrc as a reference-only git submodule under vendor/opensrc/ (pinned to 0.7.1) and add a deep-dive at .please/docs/references/opensrc.md on its architecture, fetch pipeline, and cache to compare with ASK. Update CLAUDE.md to list the new vendor; no runtime or build changes.

^{Written for commit bc27625. Summary will update on new commits.}

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!

[cubic-dev-ai]

No issues found across 4 files

_{Auto-approved: Documentation and reference-only submodule addition with no impact on core business logic or runtime execution.}

Architecture diagram

sequenceDiagram
    participant Agent as AI Agent / User
    participant CLI as NEW: opensrc CLI (Rust)
    participant Local as Project Workspace (CWD)
    participant Cache as ~/.opensrc (Global Cache)
    participant Registry as External Registry (npm/PyPI)
    participant Git as Git Host (GitHub/GitLab)

    Note over Agent,Git: NEW: opensrc "path" Fetch Pipeline Analysis

    Agent->>CLI: opensrc path <spec>
    CLI->>Cache: NEW: Check sources.json for cached <spec>
    
    alt Cache Hit
        Cache-->>CLI: Return existing path
    else Cache Miss
        opt No version in <spec>
            CLI->>Local: NEW: detect_installed_version()
            Local->>Local: Parse lockfiles (pnpm/yarn/npm) via regex
            Local-->>CLI: Resolved version (e.g. 1.2.0)
        end

        CLI->>Registry: NEW: resolve_package(name, version)
        Registry-->>CLI: Git Repo URL + Subdirectory (monorepo support)

        alt Git Clone Flow
            CLI->>Git: NEW: clone_at_tag() (depth=1)
            alt v<version> tag exists
                Git-->>CLI: Shallow clone success
            else v<version> missing
                CLI->>Git: Fallback: Clone default branch
                Git-->>CLI: Clone success (with warning)
            end
        end

        CLI->>CLI: Strip .git directory (snapshot only)
        
        CLI->>Cache: NEW: write_sources() (Atomic write)
        Note right of Cache: Temp file + Rename for concurrency
    end

    CLI-->>Agent: Print absolute path to stdout (e.g. /home/user/.opensrc/repos/...)
    
    Note over Agent,CLI: Agent then uses path in shell: cat $(opensrc path zod)/README.md

Loading

[cloudflare-workers-and-pages]

Deploying ask-registry with    Cloudflare Pages

Latest commit:	bc27625
Status:	🚫  Build failed.

View logs