@cvr/repo 1.0.0

package/README.md

@@ -0,0 +1,94 @@
+# repo
+
+Multi-registry source code cache manager. Fetch and cache source code from GitHub, npm, PyPI, and Crates.io.
+
+Inspired by [vercel-labs/opensrc](https://github.com/vercel-labs/opensrc).
+
+## Features
+
+- **Source-first**: Package registries (npm, PyPI, Crates) resolve to source git repos when possible, with tarball fallback
+- **Multi-registry**: GitHub, npm, PyPI, Crates.io support
+- **Shallow clones**: Default depth of 100 commits for fast fetching
+- **Auto-update**: Re-fetching updates existing git repos
+- **Global cache**: All repos cached at `~/.cache/repo/`
+
+## Installation
+
+```bash
+# Clone and build
+git clone https://github.com/cevr/repo.git
+cd repo
+bun install
+bun run build
+
+# Link globally
+bun link
+```
+
+## Quick Start
+
+```bash
+# Fetch a GitHub repo
+repo fetch vercel/next.js
+
+# Fetch an npm package (resolves to source repo)
+repo fetch npm:effect@3.0.0
+
+# Get the cached path
+repo path vercel/next.js
+
+# List all cached repos
+repo list
+
+# Search across all cached repos
+repo search "createServer"
+```
+
+## Spec Formats
+
+| Format | Example |
+|--------|---------|
+| GitHub | `owner/repo`, `owner/repo@v1.0.0` |
+| npm | `npm:lodash`, `npm:@effect/cli@0.73.0` |
+| PyPI | `pypi:requests@2.31.0` |
+| Crates | `crates:serde@1.0.0` |
+
+## Commands
+
+| Command | Description |
+|---------|-------------|
+| `repo fetch <spec>` | Fetch/update repository |
+| `repo path <spec>` | Get cached path |
+| `repo info <spec>` | Show repository metadata |
+| `repo list` | List cached repos |
+| `repo search <query>` | Search across cached repos |
+| `repo stats` | Cache statistics |
+| `repo remove <spec>` | Remove from cache |
+| `repo prune` | Remove old/large repos |
+| `repo clean` | Clear entire cache |
+| `repo open <spec>` | Open in editor |
+
+See [SKILL.md](./SKILL.md) for detailed usage.
+
+## Storage
+
+```
+~/.cache/repo/
+├── metadata.json              # Index
+├── {owner}/{repo}/            # GitHub repos
+└── {package}/{version}/       # Package registries
+```
+
+## Tech Stack
+
+- [Bun](https://bun.sh) - Runtime
+- [Effect](https://effect.website) - Functional TypeScript
+- [@effect/cli](https://github.com/Effect-TS/effect/tree/main/packages/cli) - CLI framework
+
+## Credits
+
+Inspired by [vercel-labs/opensrc](https://github.com/vercel-labs/opensrc) - a tool for exploring open source projects.
+
+## License
+
+MIT

package/package.json

@@ -0,0 +1,51 @@
+{
+  "name": "@cvr/repo",
+  "version": "1.0.0",
+  "type": "module",
+  "bin": {
+    "repo": "./bin/repo"
+  },
+  "files": [
+    "src",
+    "bin",
+    "tsconfig.json"
+  ],
+  "scripts": {
+    "build": "bun build src/main.ts --outfile bin/repo --compile",
+    "postinstall": "bun run build",
+    "prepublishOnly": "rm -rf bin",
+    "dev": "bun run src/main.ts",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "prepare": "effect-language-service patch",
+    "link": "ln -sf $(pwd)/bin/repo ~/.bun/bin/repo",
+    "version": "changeset version",
+    "release": "changeset publish"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/cevr/repo.git"
+  },
+  "engines": {
+    "bun": ">=1.0.0"
+  },
+  "dependencies": {
+    "@effect/cli": "^0.73.0",
+    "@effect/platform": "^0.94.1",
+    "@effect/platform-bun": "^0.87.0",
+    "effect": "^3.19.14"
+  },
+  "devDependencies": {
+    "@changesets/changelog-github": "^0.5.0",
+    "@changesets/cli": "^2.27.0",
+    "@effect/language-service": "^0.64.0",
+    "@effect/vitest": "^0.27.0",
+    "@types/bun": "^1.3.5",
+    "typescript": "^5.9.3",
+    "vitest": "^4.0.16"
+  }
+}

package/src/commands/clean.ts

@@ -0,0 +1,40 @@
+import { Command, Options } from "@effect/cli"
+import { Console, Effect } from "effect"
+import { formatBytes } from "../types.js"
+import { CacheService } from "../services/cache.js"
+import { MetadataService } from "../services/metadata.js"
+
+const confirmOption = Options.boolean("yes").pipe(
+  Options.withAlias("y"),
+  Options.withDefault(false),
+  Options.withDescription("Skip confirmation prompt")
+)
+
+export const clean = Command.make("clean", { yes: confirmOption }, ({ yes }) =>
+  Effect.gen(function* () {
+    const cache = yield* CacheService
+    const metadata = yield* MetadataService
+
+    const repos = yield* metadata.all()
+    if (repos.length === 0) {
+      yield* Console.log("Cache is already empty.")
+      return
+    }
+
+    const totalSize = repos.reduce((sum, r) => sum + r.sizeBytes, 0)
+
+    if (!yes) {
+      yield* Console.log(
+        `This will remove ${repos.length} cached repositories (${formatBytes(totalSize)}).`
+      )
+      yield* Console.log('Use --yes to confirm.')
+      return
+    }
+
+    yield* cache.removeAll()
+    yield* metadata.save({ version: 1, repos: [] })
+
+    yield* Console.log(`Removed ${repos.length} repositories.`)
+    yield* Console.log(`Freed: ${formatBytes(totalSize)}`)
+  })
+)

package/src/commands/fetch.ts

@@ -0,0 +1,152 @@
+import { Args, Command, Options } from "@effect/cli"
+import { Console, Effect } from "effect"
+import { formatBytes, specToString } from "../types.js"
+import { CacheService } from "../services/cache.js"
+import { MetadataService } from "../services/metadata.js"
+import { RegistryService } from "../services/registry.js"
+import { GitService } from "../services/git.js"
+
+const specArg = Args.text({ name: "spec" }).pipe(
+  Args.withDescription(
+    "Package spec: owner/repo, npm:package[@version], pypi:package, crates:crate"
+  )
+)
+
+const forceOption = Options.boolean("force").pipe(
+  Options.withAlias("f"),
+  Options.withDefault(false),
+  Options.withDescription("Force re-clone (removes existing and clones fresh)")
+)
+
+const updateOption = Options.boolean("update").pipe(
+  Options.withAlias("u"),
+  Options.withDefault(false),
+  Options.withDescription("Update existing repo (git pull)")
+)
+
+const fullHistoryOption = Options.boolean("full").pipe(
+  Options.withDefault(false),
+  Options.withDescription("Clone full git history (default: shallow clone with depth 100)")
+)
+
+export const fetch = Command.make(
+  "fetch",
+  { spec: specArg, force: forceOption, update: updateOption, full: fullHistoryOption },
+  ({ spec, force, update, full }) =>
+    Effect.gen(function* () {
+      const registry = yield* RegistryService
+      const cache = yield* CacheService
+      const metadata = yield* MetadataService
+      const git = yield* GitService
+
+      // Parse the spec
+      const parsedSpec = yield* registry.parseSpec(spec)
+      const specStr = specToString(parsedSpec)
+
+      // Check if already cached
+      const existing = yield* metadata.find(parsedSpec)
+      const destPath = yield* cache.getPath(parsedSpec)
+
+      if (existing) {
+        const isGit = yield* git.isGitRepo(existing.path)
+
+        if (force) {
+          // Force: remove and re-clone
+          yield* Console.log(`Force re-fetching ${specStr}...`)
+          yield* cache.remove(existing.path)
+          yield* metadata.remove(parsedSpec)
+        } else if (update || isGit) {
+          // Update existing git repo
+          if (isGit) {
+            yield* Console.log(`Updating ${specStr}...`)
+            yield* git.update(existing.path).pipe(
+              Effect.catchAll((e) =>
+                Console.log(`Update failed, repo may be up to date: ${e._tag}`)
+              )
+            )
+
+            // Recalculate size after update
+            const sizeBytes = yield* cache.getSize(existing.path)
+            const currentRef = yield* git.getCurrentRef(existing.path).pipe(
+              Effect.orElseSucceed(() => "unknown")
+            )
+
+            yield* metadata.add({
+              spec: parsedSpec,
+              fetchedAt: existing.fetchedAt,
+              lastAccessedAt: new Date().toISOString(),
+              sizeBytes,
+              path: existing.path,
+            })
+
+            yield* Console.log(`Updated: ${existing.path}`)
+            yield* Console.log(`Current ref: ${currentRef}`)
+            yield* Console.log(`Size: ${formatBytes(sizeBytes)}`)
+            return
+          } else {
+            // Not a git repo, just report it exists
+            yield* metadata.updateAccessTime(parsedSpec)
+            yield* Console.log(`Already cached at: ${existing.path}`)
+            yield* Console.log(`Size: ${formatBytes(existing.sizeBytes)}`)
+            yield* Console.log(`(Not a git repo - use --force to re-fetch)`)
+            return
+          }
+        } else {
+          // Already cached, just update access time
+          yield* metadata.updateAccessTime(parsedSpec)
+          yield* Console.log(`Already cached at: ${existing.path}`)
+          yield* Console.log(`Size: ${formatBytes(existing.sizeBytes)}`)
+          if (isGit) {
+            yield* Console.log(`Use --update to pull latest changes`)
+          }
+          yield* Console.log(`Use --force to re-fetch from scratch`)
+          return
+        }
+      }
+
+      // Fresh fetch
+      yield* Console.log(`Fetching ${specStr}...`)
+
+      // Ensure parent directory exists
+      const parentPath = destPath.split("/").slice(0, -1).join("/")
+      yield* cache.ensureDir(parentPath)
+
+      // Fetch from registry
+      yield* registry.fetch(parsedSpec, destPath, { fullHistory: full })
+
+      // Calculate size
+      const sizeBytes = yield* cache.getSize(destPath)
+
+      // Get current ref if it's a git repo
+      const isGit = yield* git.isGitRepo(destPath)
+      if (isGit) {
+        const currentRef = yield* git.getCurrentRef(destPath).pipe(
+          Effect.orElseSucceed(() => "unknown")
+        )
+        yield* Console.log(`Ref: ${currentRef}`)
+      }
+
+      // Update metadata
+      const now = new Date().toISOString()
+      yield* metadata.add({
+        spec: parsedSpec,
+        fetchedAt: now,
+        lastAccessedAt: now,
+        sizeBytes,
+        path: destPath,
+      })
+
+      yield* Console.log(`Fetched to: ${destPath}`)
+      yield* Console.log(`Size: ${formatBytes(sizeBytes)}`)
+    }).pipe(
+      Effect.catchAll((error) =>
+        Effect.gen(function* () {
+          if (typeof error === "object" && error !== null && "_tag" in error) {
+            yield* Console.error(`Error: ${error._tag}: ${JSON.stringify(error)}`)
+          } else {
+            yield* Console.error(`Error: ${String(error)}`)
+          }
+        })
+      )
+    )
+)

package/src/commands/info.ts

@@ -0,0 +1,83 @@
+import { Args, Command, Options } from "@effect/cli"
+import { Console, Effect, Option } from "effect"
+import { specToString, formatBytes, formatRelativeTime } from "../types.js"
+import { MetadataService } from "../services/metadata.js"
+import { RegistryService } from "../services/registry.js"
+import { GitService } from "../services/git.js"
+
+const specArg = Args.text({ name: "spec" }).pipe(
+  Args.withDescription("Package spec to get info for")
+)
+
+const jsonOption = Options.boolean("json").pipe(
+  Options.withDefault(false),
+  Options.withDescription("Output as JSON")
+)
+
+export const info = Command.make(
+  "info",
+  { spec: specArg, json: jsonOption },
+  ({ spec, json }) =>
+    Effect.gen(function* () {
+      const registry = yield* RegistryService
+      const metadata = yield* MetadataService
+      const git = yield* GitService
+
+      const parsedSpec = yield* registry.parseSpec(spec)
+      const existing = yield* metadata.find(parsedSpec)
+
+      if (!existing) {
+        yield* Console.error(`Not cached: ${specToString(parsedSpec)}`)
+        return
+      }
+
+      const isGit = yield* git.isGitRepo(existing.path)
+      const currentRef = isGit
+        ? yield* git
+            .getCurrentRef(existing.path)
+            .pipe(Effect.orElseSucceed(() => "unknown"))
+        : null
+
+      if (json) {
+        yield* Console.log(
+          JSON.stringify(
+            {
+              spec: {
+                registry: existing.spec.registry,
+                name: existing.spec.name,
+                version: Option.getOrNull(existing.spec.version),
+              },
+              path: existing.path,
+              sizeBytes: existing.sizeBytes,
+              sizeHuman: formatBytes(existing.sizeBytes),
+              fetchedAt: existing.fetchedAt,
+              lastAccessedAt: existing.lastAccessedAt,
+              isGitRepo: isGit,
+              currentRef,
+            },
+            null,
+            2
+          )
+        )
+      } else {
+        yield* Console.log(``)
+        yield* Console.log(`Repository Info`)
+        yield* Console.log("═".repeat(50))
+        yield* Console.log(`Spec:     ${specToString(existing.spec)}`)
+        yield* Console.log(`Registry: ${existing.spec.registry}`)
+        yield* Console.log(`Path:     ${existing.path}`)
+        yield* Console.log(`Size:     ${formatBytes(existing.sizeBytes)}`)
+        yield* Console.log(
+          `Fetched:  ${formatRelativeTime(new Date(existing.fetchedAt))}`
+        )
+        yield* Console.log(
+          `Accessed: ${formatRelativeTime(new Date(existing.lastAccessedAt))}`
+        )
+        if (isGit && currentRef) {
+          yield* Console.log(`Git ref:  ${currentRef}`)
+        }
+      }
+
+      yield* metadata.updateAccessTime(parsedSpec)
+    })
+)

package/src/commands/list.ts

@@ -0,0 +1,107 @@
+import { Command, Options } from "@effect/cli"
+import { Console, Effect, Option } from "effect"
+import { formatBytes, formatRelativeTime, specToString } from "../types.js"
+import { MetadataService } from "../services/metadata.js"
+
+const registryOption = Options.choice("registry", [
+  "github",
+  "npm",
+  "pypi",
+  "crates",
+] as const).pipe(
+  Options.withAlias("r"),
+  Options.optional,
+  Options.withDescription("Filter by registry")
+)
+
+const jsonOption = Options.boolean("json").pipe(
+  Options.withDefault(false),
+  Options.withDescription("Output as JSON")
+)
+
+const sortOption = Options.choice("sort", [
+  "date",
+  "size",
+  "name",
+] as const).pipe(
+  Options.withAlias("s"),
+  Options.withDefault("date" as const),
+  Options.withDescription("Sort by: date, size, name")
+)
+
+export const list = Command.make(
+  "list",
+  { registry: registryOption, json: jsonOption, sort: sortOption },
+  ({ registry, json, sort }) =>
+    Effect.gen(function* () {
+      const metadata = yield* MetadataService
+      let repos = yield* metadata.all()
+
+      // Filter by registry if specified
+      if (Option.isSome(registry)) {
+        repos = repos.filter((r) => r.spec.registry === registry.value)
+      }
+
+      // Sort
+      const sorted = [...repos].sort((a, b) => {
+        switch (sort) {
+          case "date":
+            return (
+              new Date(b.lastAccessedAt).getTime() -
+              new Date(a.lastAccessedAt).getTime()
+            )
+          case "size":
+            return b.sizeBytes - a.sizeBytes
+          case "name":
+            return a.spec.name.localeCompare(b.spec.name)
+        }
+      })
+
+      if (json) {
+        yield* Console.log(
+          JSON.stringify(
+            {
+              repos: sorted.map((r) => ({
+                ...r,
+                spec: {
+                  registry: r.spec.registry,
+                  name: r.spec.name,
+                  version: Option.getOrNull(r.spec.version),
+                },
+              })),
+              total: sorted.length,
+              totalSize: sorted.reduce((sum, r) => sum + r.sizeBytes, 0),
+            },
+            null,
+            2
+          )
+        )
+        return
+      }
+
+      if (sorted.length === 0) {
+        yield* Console.log("No repositories cached.")
+        yield* Console.log('Use "repo fetch <spec>" to cache a repository.')
+        return
+      }
+
+      yield* Console.log("")
+      yield* Console.log(`Cached Repositories (${sorted.length})`)
+      yield* Console.log("═".repeat(80))
+
+      for (const repo of sorted) {
+        const spec = specToString(repo.spec)
+        const size = formatBytes(repo.sizeBytes)
+        const date = formatRelativeTime(new Date(repo.lastAccessedAt))
+        const registryStr = repo.spec.registry.padEnd(6)
+
+        yield* Console.log(
+          `${registryStr}  ${spec.padEnd(40)}  ${size.padStart(10)}  ${date}`
+        )
+      }
+
+      yield* Console.log("═".repeat(80))
+      const totalSize = sorted.reduce((sum, r) => sum + r.sizeBytes, 0)
+      yield* Console.log(`Total: ${formatBytes(totalSize)}`)
+    })
+)

package/src/commands/open.ts

@@ -0,0 +1,89 @@
+import { Args, Command, Options } from "@effect/cli"
+import { Console, Effect, Option } from "effect"
+import { OpenError, specToString } from "../types.js"
+import { MetadataService } from "../services/metadata.js"
+import { RegistryService } from "../services/registry.js"
+
+const specArg = Args.text({ name: "spec" }).pipe(
+  Args.withDescription("Package spec to open")
+)
+
+const finderOption = Options.boolean("finder").pipe(
+  Options.withAlias("f"),
+  Options.withDefault(false),
+  Options.withDescription("Open in Finder instead of editor")
+)
+
+const editorOption = Options.text("editor").pipe(
+  Options.withAlias("e"),
+  Options.optional,
+  Options.withDescription("Editor to use (defaults to $EDITOR or code)")
+)
+
+export const open = Command.make(
+  "open",
+  { spec: specArg, finder: finderOption, editor: editorOption },
+  ({ spec, finder, editor }) =>
+    Effect.gen(function* () {
+      const registry = yield* RegistryService
+      const metadata = yield* MetadataService
+
+      // Parse the spec
+      const parsedSpec = yield* registry.parseSpec(spec)
+
+      // Find in metadata
+      const existing = yield* metadata.find(parsedSpec)
+      if (!existing) {
+        yield* Console.log(`Not found: ${specToString(parsedSpec)}`)
+        yield* Console.log('Use "repo fetch" first to cache it.')
+        return
+      }
+
+      // Update access time
+      yield* metadata.updateAccessTime(parsedSpec)
+
+      if (finder) {
+        // Open in Finder (macOS)
+        const proc = Bun.spawn(["open", existing.path], {
+          stdout: "pipe",
+          stderr: "pipe",
+        })
+        yield* Effect.tryPromise({
+          try: () => proc.exited.then((code) => {
+            if (code !== 0) throw new Error(`exit code ${code}`)
+          }),
+          catch: (e) => new OpenError({ command: "open", cause: e }),
+        })
+        yield* Console.log(`Opened in Finder: ${existing.path}`)
+      } else {
+        // Open in editor
+        const editorCmd = Option.isSome(editor)
+          ? editor.value
+          : process.env.EDITOR ?? "code"
+
+        const proc = Bun.spawn([editorCmd, existing.path], {
+          stdout: "pipe",
+          stderr: "pipe",
+        })
+        yield* Effect.tryPromise({
+          try: () => proc.exited.then((code) => {
+            if (code !== 0) throw new Error(`exit code ${code}`)
+          }),
+          catch: (e) => new OpenError({ command: editorCmd, cause: e }),
+        })
+        yield* Console.log(`Opened in ${editorCmd}: ${existing.path}`)
+      }
+    }).pipe(
+      Effect.catchAll((error) =>
+        Effect.gen(function* () {
+          if (typeof error === "object" && error !== null && "_tag" in error) {
+            yield* Console.error(
+              `Error: ${(error as { _tag: string })._tag}: ${JSON.stringify(error)}`
+            )
+          } else {
+            yield* Console.error(`Error: ${String(error)}`)
+          }
+        })
+      )
+    )
+)

package/src/commands/path.ts

@@ -0,0 +1,38 @@
+import { Args, Command, Options } from "@effect/cli"
+import { Console, Effect } from "effect"
+import { NotFoundError, specToString } from "../types.js"
+import { MetadataService } from "../services/metadata.js"
+import { RegistryService } from "../services/registry.js"
+
+const specArg = Args.text({ name: "spec" }).pipe(
+  Args.withDescription("Package spec to get path for")
+)
+
+const quietOption = Options.boolean("quiet").pipe(
+  Options.withAlias("q"),
+  Options.withDefault(false),
+  Options.withDescription("Output only the path, exit 1 if not cached")
+)
+
+export const path = Command.make(
+  "path",
+  { spec: specArg, quiet: quietOption },
+  ({ spec, quiet }) =>
+    Effect.gen(function* () {
+      const registry = yield* RegistryService
+      const metadata = yield* MetadataService
+
+      const parsedSpec = yield* registry.parseSpec(spec)
+      const existing = yield* metadata.find(parsedSpec)
+
+      if (!existing) {
+        if (!quiet) {
+          yield* Console.error(`Not cached: ${specToString(parsedSpec)}`)
+          yield* Console.error(`Run: repo fetch ${spec}`)
+        }
+        return yield* Effect.fail(new NotFoundError({ spec: parsedSpec }))
+      }
+
+      yield* Console.log(existing.path)
+    }).pipe(Effect.catchAll(() => Effect.void))
+)